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