/gecko_api/include/nscore.h

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