/gecko_api/include/nscore.h

http://firefox-mac-pdf.googlecode.com/ · C Header · 494 lines · 217 code · 61 blank · 216 comment · 18 complexity · 90cf889c5caded753b3cd89ee59103ae MD5 · raw file

  1. /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4. *
  5. * The contents of this file are subject to the Mozilla Public License Version
  6. * 1.1 (the "License"); you may not use this file except in compliance with
  7. * the License. You may obtain a copy of the License at
  8. * http://www.mozilla.org/MPL/
  9. *
  10. * Software distributed under the License is distributed on an "AS IS" basis,
  11. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12. * for the specific language governing rights and limitations under the
  13. * License.
  14. *
  15. * The Original Code is mozilla.org code.
  16. *
  17. * The Initial Developer of the Original Code is
  18. * Netscape Communications Corporation.
  19. * Portions created by the Initial Developer are Copyright (C) 1998
  20. * the Initial Developer. All Rights Reserved.
  21. *
  22. * Contributor(s):
  23. *
  24. * Alternatively, the contents of this file may be used under the terms of
  25. * either of the GNU General Public License Version 2 or later (the "GPL"),
  26. * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27. * in which case the provisions of the GPL or the LGPL are applicable instead
  28. * of those above. If you wish to allow use of your version of this file only
  29. * under the terms of either the GPL or the LGPL, and not to allow others to
  30. * use your version of this file under the terms of the MPL, indicate your
  31. * decision by deleting the provisions above and replace them with the notice
  32. * and other provisions required by the GPL or the LGPL. If you do not delete
  33. * the provisions above, a recipient may use your version of this file under
  34. * the terms of any one of the MPL, the GPL or the LGPL.
  35. *
  36. * ***** END LICENSE BLOCK ***** */
  37. #ifndef nscore_h___
  38. #define nscore_h___
  39. /**
  40. * Make sure that we have the proper platform specific
  41. * c++ definitions needed by nscore.h
  42. */
  43. #ifndef _XPCOM_CONFIG_H_
  44. #include "xpcom-config.h"
  45. #endif
  46. /**
  47. * Incorporate the core NSPR data types which XPCOM uses.
  48. */
  49. #include "prtypes.h"
  50. /* Core XPCOM declarations. */
  51. /**
  52. * Macros defining the target platform...
  53. */
  54. #ifdef _WIN32
  55. #define NS_WIN32 1
  56. #elif defined(__unix)
  57. #define NS_UNIX 1
  58. #elif defined(XP_OS2)
  59. #define NS_OS2 1
  60. #endif
  61. /*----------------------------------------------------------------------*/
  62. /* Import/export defines */
  63. /**
  64. * Using the visibility("hidden") attribute allows the compiler to use
  65. * PC-relative addressing to call this function. If a function does not
  66. * access any global data, and does not call any methods which are not either
  67. * file-local or hidden, then on ELF systems we avoid loading the address of
  68. * the PLT into a register at the start of the function, which reduces code
  69. * size and frees up a register for general use.
  70. *
  71. * As a general rule, this should be used for any non-exported symbol
  72. * (including virtual method implementations). NS_IMETHOD uses this by
  73. * default; if you need to have your NS_IMETHOD functions exported, you can
  74. * wrap your class as follows:
  75. *
  76. * #undef IMETHOD_VISIBILITY
  77. * #define IMETHOD_VISIBILITY NS_VISIBILITY_DEFAULT
  78. *
  79. * class Foo {
  80. * ...
  81. * };
  82. *
  83. * #undef IMETHOD_VISIBILITY
  84. * #define IMETHOD_VISIBILITY NS_VISIBILITY_HIDDEN
  85. *
  86. * Don't forget to change the visibility back to hidden before the end
  87. * of a header!
  88. *
  89. * Other examples:
  90. *
  91. * NS_HIDDEN_(int) someMethod();
  92. * SomeCtor() NS_HIDDEN;
  93. */
  94. #ifdef HAVE_VISIBILITY_HIDDEN_ATTRIBUTE
  95. #define NS_VISIBILITY_HIDDEN __attribute__ ((visibility ("hidden")))
  96. #else
  97. #define NS_VISIBILITY_HIDDEN
  98. #endif
  99. #if defined(HAVE_VISIBILITY_ATTRIBUTE)
  100. #define NS_VISIBILITY_DEFAULT __attribute__ ((visibility ("default")))
  101. #else
  102. #define NS_VISIBILITY_DEFAULT
  103. #endif
  104. #define NS_HIDDEN_(type) NS_VISIBILITY_HIDDEN type
  105. #define NS_EXTERNAL_VIS_(type) NS_VISIBILITY_DEFAULT type
  106. #define NS_HIDDEN NS_VISIBILITY_HIDDEN
  107. #define NS_EXTERNAL_VIS NS_VISIBILITY_DEFAULT
  108. #undef IMETHOD_VISIBILITY
  109. #define IMETHOD_VISIBILITY NS_VISIBILITY_HIDDEN
  110. /**
  111. * Mark a function as using a potentially non-standard function calling
  112. * convention. This can be used on functions that are called very
  113. * frequently, to reduce the overhead of the function call. It is still worth
  114. * using the macro for C++ functions which take no parameters since it allows
  115. * passing |this| in a register.
  116. *
  117. * - Do not use this on any scriptable interface method since xptcall won't be
  118. * aware of the different calling convention.
  119. * - This must appear on the declaration, not the definition.
  120. * - Adding this to a public function _will_ break binary compatibility.
  121. * - This may be used on virtual functions but you must ensure it is applied
  122. * to all implementations - the compiler will _not_ warn but it will crash.
  123. * - This has no effect for inline functions or functions which take a
  124. * variable number of arguments.
  125. * - __fastcall on windows should not be applied to class
  126. * constructors/destructors - use the NS_CONSTRUCTOR_FASTCALL macro for
  127. * constructors/destructors.
  128. *
  129. * Examples: int NS_FASTCALL func1(char *foo);
  130. * NS_HIDDEN_(int) NS_FASTCALL func2(char *foo);
  131. */
  132. #if defined(__i386__) && defined(__GNUC__) && (__GNUC__ >= 3) && !defined(XP_OS2)
  133. #define NS_FASTCALL __attribute__ ((regparm (3), stdcall))
  134. #define NS_CONSTRUCTOR_FASTCALL __attribute__ ((regparm (3), stdcall))
  135. #elif defined(XP_WIN)
  136. #define NS_FASTCALL __fastcall
  137. #define NS_CONSTRUCTOR_FASTCALL
  138. #else
  139. #define NS_FASTCALL
  140. #define NS_CONSTRUCTOR_FASTCALL
  141. #endif
  142. /*
  143. * NS_DEFCALL undoes the effect of a global regparm/stdcall setting
  144. * so that xptcall works correctly.
  145. */
  146. #if defined(__i386__) && defined(__GNUC__) && (__GNUC__ >= 3) && !defined(XP_OS2)
  147. #define NS_DEFCALL __attribute__ ((regparm (0), cdecl))
  148. #else
  149. #define NS_DEFCALL
  150. #endif
  151. #ifdef NS_WIN32
  152. #define NS_IMPORT __declspec(dllimport)
  153. #define NS_IMPORT_(type) __declspec(dllimport) type __stdcall
  154. #define NS_EXPORT __declspec(dllexport)
  155. #define NS_EXPORT_(type) __declspec(dllexport) type __stdcall
  156. #define NS_IMETHOD_(type) virtual type __stdcall
  157. #define NS_IMETHODIMP_(type) type __stdcall
  158. #define NS_METHOD_(type) type __stdcall
  159. #define NS_CALLBACK_(_type, _name) _type (__stdcall * _name)
  160. #define NS_STDCALL __stdcall
  161. #define NS_FROZENCALL __cdecl
  162. /*
  163. These are needed to mark static members in exported classes, due to
  164. gcc bug XXX insert bug# here.
  165. */
  166. #define NS_EXPORT_STATIC_MEMBER_(type) type
  167. #define NS_IMPORT_STATIC_MEMBER_(type) type
  168. #elif defined(XP_OS2) && defined(__declspec)
  169. #define NS_IMPORT __declspec(dllimport)
  170. #define NS_IMPORT_(type) type __declspec(dllimport)
  171. #define NS_EXPORT __declspec(dllexport)
  172. #define NS_EXPORT_(type) type __declspec(dllexport)
  173. #define NS_IMETHOD_(type) virtual type
  174. #define NS_IMETHODIMP_(type) type
  175. #define NS_METHOD_(type) type
  176. #define NS_CALLBACK_(_type, _name) _type (* _name)
  177. #define NS_STDCALL
  178. #define NS_FROZENCALL
  179. #define NS_EXPORT_STATIC_MEMBER_(type) NS_EXTERNAL_VIS_(type)
  180. #define NS_IMPORT_STATIC_MEMBER_(type) NS_EXTERNAL_VIS_(type)
  181. #else
  182. #define NS_IMPORT NS_EXTERNAL_VIS
  183. #define NS_IMPORT_(type) NS_EXTERNAL_VIS_(type)
  184. #define NS_EXPORT NS_EXTERNAL_VIS
  185. #define NS_EXPORT_(type) NS_EXTERNAL_VIS_(type)
  186. #define NS_IMETHOD_(type) virtual IMETHOD_VISIBILITY type NS_DEFCALL
  187. #define NS_IMETHODIMP_(type) type
  188. #define NS_METHOD_(type) type
  189. #define NS_CALLBACK_(_type, _name) _type (* _name)
  190. #define NS_STDCALL
  191. #define NS_FROZENCALL
  192. #define NS_EXPORT_STATIC_MEMBER_(type) NS_EXTERNAL_VIS_(type)
  193. #define NS_IMPORT_STATIC_MEMBER_(type) NS_EXTERNAL_VIS_(type)
  194. #endif
  195. /**
  196. * Macro for creating typedefs for pointer-to-member types which are
  197. * declared with stdcall. It is important to use this for any type which is
  198. * declared as stdcall (i.e. NS_IMETHOD). For example, instead of writing:
  199. *
  200. * typedef nsresult (nsIFoo::*someType)(nsISupports* arg);
  201. *
  202. * you should write:
  203. *
  204. * typedef
  205. * NS_STDCALL_FUNCPROTO(nsresult, someType, nsIFoo, typeFunc, (nsISupports*));
  206. *
  207. * where nsIFoo::typeFunc is any method declared as
  208. * NS_IMETHOD typeFunc(nsISupports*);
  209. *
  210. * XXX this can be simplified to always use the non-typeof implementation
  211. * when http://gcc.gnu.org/bugzilla/show_bug.cgi?id=11893 is fixed.
  212. */
  213. #ifdef __GNUC__
  214. #define NS_STDCALL_FUNCPROTO(ret, name, class, func, args) \
  215. typeof(&class::func) name
  216. #else
  217. #define NS_STDCALL_FUNCPROTO(ret, name, class, func, args) \
  218. ret (NS_STDCALL class::*name) args
  219. #endif
  220. /**
  221. * Deprecated declarations.
  222. */
  223. #if (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
  224. # define NS_DEPRECATED __attribute__((deprecated))
  225. #elif defined(_MSC_VER) && (_MSC_VER >= 1300)
  226. # define NS_DEPRECATED __declspec(deprecated)
  227. #else
  228. # define NS_DEPRECATED
  229. #endif
  230. /**
  231. * Attributes defined to help Dehydra GCC analysis.
  232. */
  233. #ifdef DEHYDRA_GCC
  234. # define NS_SCRIPTABLE __attribute__((user("script")))
  235. #else
  236. # define NS_SCRIPTABLE
  237. #endif
  238. /**
  239. * Generic API modifiers which return the standard XPCOM nsresult type
  240. */
  241. #define NS_IMETHOD NS_IMETHOD_(nsresult)
  242. #define NS_IMETHODIMP NS_IMETHODIMP_(nsresult)
  243. #define NS_METHOD NS_METHOD_(nsresult)
  244. #define NS_CALLBACK(_name) NS_CALLBACK_(nsresult, _name)
  245. /**
  246. * Import/Export macros for XPCOM APIs
  247. */
  248. #ifdef __cplusplus
  249. #define NS_EXTERN_C extern "C"
  250. #else
  251. #define NS_EXTERN_C
  252. #endif
  253. #define EXPORT_XPCOM_API(type) NS_EXTERN_C NS_EXPORT type NS_FROZENCALL
  254. #define IMPORT_XPCOM_API(type) NS_EXTERN_C NS_IMPORT type NS_FROZENCALL
  255. #define GLUE_XPCOM_API(type) NS_EXTERN_C NS_HIDDEN_(type) NS_FROZENCALL
  256. #ifdef _IMPL_NS_COM
  257. #define XPCOM_API(type) EXPORT_XPCOM_API(type)
  258. #elif defined(XPCOM_GLUE)
  259. #define XPCOM_API(type) GLUE_XPCOM_API(type)
  260. #else
  261. #define XPCOM_API(type) IMPORT_XPCOM_API(type)
  262. #endif
  263. #ifdef MOZ_ENABLE_LIBXUL
  264. #define NS_COM
  265. #elif defined(_IMPL_NS_COM)
  266. #define NS_COM NS_EXPORT
  267. #elif defined(XPCOM_GLUE)
  268. #define NS_COM
  269. #else
  270. #define NS_COM NS_IMPORT
  271. #endif
  272. #ifdef MOZILLA_INTERNAL_API
  273. # define NS_COM_GLUE NS_COM
  274. /*
  275. The frozen string API has different definitions of nsAC?String
  276. classes than the internal API. On systems that explicitly declare
  277. dllexport symbols this is not a problem, but on ELF systems
  278. internal symbols can accidentally "shine through"; we rename the
  279. internal classes to avoid symbol conflicts.
  280. */
  281. # define nsAString nsAString_internal
  282. # define nsACString nsACString_internal
  283. #else
  284. # ifdef HAVE_VISIBILITY_ATTRIBUTE
  285. # define NS_COM_GLUE NS_VISIBILITY_HIDDEN
  286. # else
  287. # define NS_COM_GLUE
  288. # endif
  289. #endif
  290. /**
  291. * NS_NO_VTABLE is emitted by xpidl in interface declarations whenever
  292. * xpidl can determine that the interface can't contain a constructor.
  293. * This results in some space savings and possible runtime savings -
  294. * see bug 49416. We undefine it first, as xpidl-generated headers
  295. * define it for IDL uses that don't include this file.
  296. */
  297. #ifdef NS_NO_VTABLE
  298. #undef NS_NO_VTABLE
  299. #endif
  300. #if defined(_MSC_VER) && _MSC_VER >= 1100
  301. #define NS_NO_VTABLE __declspec(novtable)
  302. #else
  303. #define NS_NO_VTABLE
  304. #endif
  305. /**
  306. * Generic XPCOM result data type
  307. */
  308. typedef PRUint32 nsresult;
  309. /**
  310. * Reference count values
  311. *
  312. * This is the return type for AddRef() and Release() in nsISupports.
  313. * IUnknown of COM returns an unsigned long from equivalent functions.
  314. * The following ifdef exists to maintain binary compatibility with
  315. * IUnknown.
  316. */
  317. #if defined(XP_WIN) && PR_BYTES_PER_LONG == 4
  318. typedef unsigned long nsrefcnt;
  319. #else
  320. typedef PRUint32 nsrefcnt;
  321. #endif
  322. /**
  323. * The preferred symbol for null.
  324. */
  325. #define nsnull 0
  326. #include "nsError.h"
  327. /* ------------------------------------------------------------------------ */
  328. /* Casting macros for hiding C++ features from older compilers */
  329. /*
  330. All our compiler support template specialization, but not all support the
  331. |template <>| notation. The compiler that don't understand this notation
  332. just omit it for specialization.
  333. Need to add an autoconf test for this.
  334. */
  335. /* under Metrowerks (Mac), we don't have autoconf yet */
  336. #ifdef __MWERKS__
  337. #define HAVE_CPP_PARTIAL_SPECIALIZATION
  338. #define HAVE_CPP_MODERN_SPECIALIZE_TEMPLATE_SYNTAX
  339. #define HAVE_CPP_ACCESS_CHANGING_USING
  340. #define HAVE_CPP_AMBIGUITY_RESOLVING_USING
  341. #define HAVE_CPP_EXPLICIT
  342. #define HAVE_CPP_TYPENAME
  343. #define HAVE_CPP_BOOL
  344. #define HAVE_CPP_NAMESPACE_STD
  345. #define HAVE_CPP_UNAMBIGUOUS_STD_NOTEQUAL
  346. #define HAVE_CPP_2BYTE_WCHAR_T
  347. #endif
  348. /* under VC++ (Windows), we don't have autoconf yet */
  349. #if defined(_MSC_VER) && (_MSC_VER>=1100)
  350. /* VC++ 5.0 and greater implement template specialization, 4.2 is unknown */
  351. #define HAVE_CPP_MODERN_SPECIALIZE_TEMPLATE_SYNTAX
  352. #define HAVE_CPP_EXPLICIT
  353. #define HAVE_CPP_TYPENAME
  354. #define HAVE_CPP_ACCESS_CHANGING_USING
  355. #if (_MSC_VER==1100)
  356. /* VC++5.0 has an internal compiler error (sometimes) without this */
  357. #undef HAVE_CPP_ACCESS_CHANGING_USING
  358. #endif
  359. #define HAVE_CPP_NAMESPACE_STD
  360. #define HAVE_CPP_UNAMBIGUOUS_STD_NOTEQUAL
  361. #define HAVE_CPP_2BYTE_WCHAR_T
  362. #endif
  363. #ifndef __PRUNICHAR__
  364. #define __PRUNICHAR__
  365. /* For now, don't use wchar_t on Unix because it breaks the Netscape
  366. * commercial build. When this is fixed there will be no need for the
  367. * |reinterpret_cast| in nsLiteralString.h either.
  368. */
  369. #if defined(HAVE_CPP_2BYTE_WCHAR_T) && defined(NS_WIN32)
  370. typedef wchar_t PRUnichar;
  371. #else
  372. typedef PRUint16 PRUnichar;
  373. #endif
  374. #endif
  375. /*
  376. If the compiler doesn't support |explicit|, we'll just make it go away, trusting
  377. that the builds under compilers that do have it will keep us on the straight and narrow.
  378. */
  379. #ifndef HAVE_CPP_EXPLICIT
  380. #define explicit
  381. #endif
  382. #ifndef HAVE_CPP_TYPENAME
  383. #define typename
  384. #endif
  385. #ifdef HAVE_CPP_MODERN_SPECIALIZE_TEMPLATE_SYNTAX
  386. #define NS_SPECIALIZE_TEMPLATE template <>
  387. #else
  388. #define NS_SPECIALIZE_TEMPLATE
  389. #endif
  390. /*
  391. * Use these macros to do 64bit safe pointer conversions.
  392. */
  393. #define NS_PTR_TO_INT32(x) ((PRInt32) (PRWord) (x))
  394. #define NS_PTR_TO_UINT32(x) ((PRUint32) (PRWord) (x))
  395. #define NS_INT32_TO_PTR(x) ((void *) (PRWord) (x))
  396. /*
  397. * Use NS_STRINGIFY to form a string literal from the value of a macro.
  398. */
  399. #define NS_STRINGIFY_HELPER(x_) #x_
  400. #define NS_STRINGIFY(x_) NS_STRINGIFY_HELPER(x_)
  401. /*
  402. * These macros allow you to give a hint to the compiler about branch
  403. * probability so that it can better optimize. Use them like this:
  404. *
  405. * if (NS_LIKELY(v == 1)) {
  406. * ... expected code path ...
  407. * }
  408. *
  409. * if (NS_UNLIKELY(v == 0)) {
  410. * ... non-expected code path ...
  411. * }
  412. *
  413. * These macros are guaranteed to always return 0 or 1.
  414. * The NS_FAILED/NS_SUCCEEDED macros depends on this.
  415. * @return 0 or 1
  416. */
  417. #if defined(__GNUC__) && (__GNUC__ > 2)
  418. #define NS_LIKELY(x) (__builtin_expect(!!(x), 1))
  419. #define NS_UNLIKELY(x) (__builtin_expect(!!(x), 0))
  420. #else
  421. #define NS_LIKELY(x) (!!(x))
  422. #define NS_UNLIKELY(x) (!!(x))
  423. #endif
  424. /*
  425. * If we're being linked as standalone glue, we don't want a dynamic dependency
  426. * on NSPR libs, so we skip the debug thread-safety checks, and we cannot use
  427. * the THREADSAFE_ISUPPORTS macros.
  428. */
  429. #if defined(XPCOM_GLUE) && !defined(XPCOM_GLUE_USE_NSPR)
  430. #define XPCOM_GLUE_AVOID_NSPR
  431. #endif
  432. #endif /* nscore_h___ */