xpcom/glue/nsMemory.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef nsMemory_h__
   8 #define nsMemory_h__
   9
  10 #include "nsXPCOM.h"
  11
  12 class nsIMemory;
  13
  14 #define NS_MEMORY_CONTRACTID "@mozilla.org/xpcom/memory-service;1"
  15 #define NS_MEMORY_CID                                \
  16 { /* 30a04e40-38e7-11d4-8cf5-0060b0fc14a3 */         \
  17     0x30a04e40,                                      \
  18     0x38e7,                                          \
  19     0x11d4,                                          \
  20     {0x8c, 0xf5, 0x00, 0x60, 0xb0, 0xfc, 0x14, 0xa3} \
  21 }
  22
  23
  24 /**
  25  * Static helper routines to manage memory. These routines allow easy access
  26  * to xpcom's built-in (global) nsIMemory implementation, without needing
  27  * to go through the service manager to get it. However this requires clients
  28  * to link with the xpcom DLL.
  29  *
  30  * This class is not threadsafe and is intented for use only on the main
  31  * thread.
  32  */
  33 class nsMemory
  34 {
  35 public:
  36   static NS_HIDDEN_(void*) Alloc(size_t aSize)
  37   {
  38     return NS_Alloc(aSize);
  39   }
  40
  41   static NS_HIDDEN_(void*) Realloc(void* aPtr, size_t aSize)
  42   {
  43     return NS_Realloc(aPtr, aSize);
  44   }
  45
  46   static NS_HIDDEN_(void) Free(void* aPtr)
  47   {
  48     NS_Free(aPtr);
  49   }
  50
  51   static nsresult   HeapMinimize(bool aImmediate);
  52   static void*      Clone(const void* aPtr, size_t aSize);
  53   static nsIMemory* GetGlobalMemoryService();       // AddRefs
  54 };
  55
  56 /**
  57  * Macro to free all elements of an XPCOM array of a given size using
  58  * freeFunc, then frees the array itself using nsMemory::Free().
  59  *
  60  * Note that this macro (and its wrappers) can be used to deallocate a
  61  * partially- or completely-built array while unwinding an error
  62  * condition inside the XPCOM routine that was going to return the
  63  * array.  For this to work on a partially-built array, your code
  64  * needs to be building the array from index 0 upwards, and simply
  65  * pass the number of elements that have already been built (and thus
  66  * need to be freed) as |size|.
  67  *
  68  * Thanks to <alecf@netscape.com> for suggesting this form, which
  69  * allows the macro to be used with NS_RELEASE / NS_RELEASE_IF in
  70  * addition to nsMemory::Free.
  71  *
  72  * @param size      Number of elements in the array.  If not a constant, this
  73  *                  should be a int32_t.  Note that this means this macro
  74  *                  will not work if size >= 2^31.
  75  * @param array     The array to be freed.
  76  * @param freeFunc  The function or macro to be used to free it.
  77  *                  For arrays of nsISupports (or any class derived
  78  *                  from it), NS_IF_RELEASE (or NS_RELEASE) should be
  79  *                  passed as freeFunc.  For most (all?) other pointer
  80  *                  types (including XPCOM strings and wstrings),
  81  *                  nsMemory::Free should be used, since the
  82  *                  shared-allocator (nsMemory) is what will have been
  83  *                  used to allocate the memory.
  84  */
  85 #define NS_FREE_XPCOM_POINTER_ARRAY(size, array, freeFunc)                    \
  86     PR_BEGIN_MACRO                                                            \
  87         int32_t iter_ = int32_t(size);                                        \
  88         while (--iter_ >= 0)                                                  \
  89             freeFunc((array)[iter_]);                                         \
  90         NS_Free((array));                                                     \
  91     PR_END_MACRO
  92
  93 // convenience macros for commonly used calls.  mmmmm.  syntactic sugar.
  94
  95 /**
  96  * Macro to free arrays of non-refcounted objects allocated by the
  97  * shared allocator (nsMemory) such as strings and wstrings.  A
  98  * convenience wrapper around NS_FREE_XPCOM_POINTER_ARRAY.
  99  *
 100  * @param size      Number of elements in the array.  If not a constant, this
 101  *                  should be a int32_t.  Note that this means this macro
 102  *                  will not work if size >= 2^31.
 103  * @param array     The array to be freed.
 104  */
 105 #define NS_FREE_XPCOM_ALLOCATED_POINTER_ARRAY(size, array)                    \
 106     NS_FREE_XPCOM_POINTER_ARRAY((size), (array), NS_Free)
 107
 108 /**
 109  * Macro to free an array of pointers to nsISupports (or classes
 110  * derived from it).  A convenience wrapper around
 111  * NS_FREE_XPCOM_POINTER_ARRAY.
 112  *
 113  * Note that if you know that none of your nsISupports pointers are
 114  * going to be 0, you can gain a bit of speed by calling
 115  * NS_FREE_XPCOM_POINTER_ARRAY directly and using NS_RELEASE as your
 116  * free function.
 117  *
 118  * @param size      Number of elements in the array.  If not a constant, this
 119  *                  should be a int32_t.  Note that this means this macro
 120  *                  will not work if size >= 2^31.
 121  * @param array     The array to be freed.
 122  */
 123 #define NS_FREE_XPCOM_ISUPPORTS_POINTER_ARRAY(size, array)                    \
 124     NS_FREE_XPCOM_POINTER_ARRAY((size), (array), NS_IF_RELEASE)
 125
 126 /**
 127  * A macro, NS_ALIGNMENT_OF(t_) that determines the alignment
 128  * requirements of a type.
 129  */
 130 namespace mozilla {
 131 template<class T>
 132 struct AlignmentTestStruct
 133 {
 134   char c;
 135   T t;
 136 };
 137 }
 138
 139 #define NS_ALIGNMENT_OF(t_) \
 140   (sizeof(mozilla::AlignmentTestStruct<t_>) - sizeof(t_))
 141
 142 /**
 143  * An enumeration type used to represent a method of assignment.
 144  */
 145 enum nsAssignmentType
 146 {
 147   NS_ASSIGNMENT_COPY,   // copy by value
 148   NS_ASSIGNMENT_DEPEND, // copy by reference
 149   NS_ASSIGNMENT_ADOPT   // copy by reference (take ownership of resource)
 150 };
 151
 152 #endif // nsMemory_h__
 153