js/public/MemoryFunctions.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /* Low-level memory-allocation functions. */
   7
   8 #ifndef js_MemoryFunctions_h
   9 #define js_MemoryFunctions_h
  10
  11 #include "mozilla/Assertions.h"  // MOZ_ASSERT
  12
  13 #include <stddef.h>  // size_t
  14
  15 #include "jstypes.h"  // JS_PUBLIC_API
  16
  17 struct JS_PUBLIC_API JSContext;
  18 class JS_PUBLIC_API JSObject;
  19 struct JS_PUBLIC_API JSRuntime;
  20
  21 extern JS_PUBLIC_API void* JS_malloc(JSContext* cx, size_t nbytes);
  22
  23 extern JS_PUBLIC_API void* JS_realloc(JSContext* cx, void* p, size_t oldBytes,
  24                                       size_t newBytes);
  25
  26 /**
  27  * A wrapper for |js_free(p)| that may delay |js_free(p)| invocation as a
  28  * performance optimization.  |cx| may be nullptr.
  29  */
  30 extern JS_PUBLIC_API void JS_free(JSContext* cx, void* p);
  31
  32 /**
  33  * Same as above, but for buffers that will be used with the BYOB
  34  * (Bring Your Own Buffer) JSString creation functions, such as
  35  * JS_NewLatin1String and JS_NewUCString
  36  */
  37 extern JS_PUBLIC_API void* JS_string_malloc(JSContext* cx, size_t nbytes);
  38
  39 extern JS_PUBLIC_API void* JS_string_realloc(JSContext* cx, void* p,
  40                                              size_t oldBytes, size_t newBytes);
  41
  42 extern JS_PUBLIC_API void JS_string_free(JSContext* cx, void* p);
  43
  44 namespace JS {
  45
  46 /**
  47  * The different possible memory uses to pass to Add/RemoveAssociatedMemory.
  48  */
  49 #define JS_FOR_EACH_PUBLIC_MEMORY_USE(_) \
  50   _(XPCWrappedNative)                    \
  51   _(DOMBinding)                          \
  52   _(CTypeFFIType)                        \
  53   _(CTypeFFITypeElements)                \
  54   _(CTypeFunctionInfo)                   \
  55   _(CTypeFieldInfo)                      \
  56   _(CDataBufferPtr)                      \
  57   _(CDataBuffer)                         \
  58   _(CClosureInfo)                        \
  59   _(CTypesInt64)                         \
  60   _(Embedding1)                          \
  61   _(Embedding2)                          \
  62   _(Embedding3)                          \
  63   _(Embedding4)                          \
  64   _(Embedding5)
  65
  66 enum class MemoryUse : uint8_t {
  67 #define DEFINE_MEMORY_USE(Name) Name,
  68   JS_FOR_EACH_PUBLIC_MEMORY_USE(DEFINE_MEMORY_USE)
  69 #undef DEFINE_MEMORY_USE
  70 };
  71
  72 /**
  73  * Advise the GC of external memory owned by a JSObject. This is used to
  74  * determine when to collect zones. Calls must be matched by calls to
  75  * RemoveAssociatedMemory() when the memory is deallocated or no longer owned by
  76  * the object.
  77  */
  78 extern JS_PUBLIC_API void AddAssociatedMemory(JSObject* obj, size_t nbytes,
  79                                               MemoryUse use);
  80
  81 /**
  82  * Advise the GC that external memory reported by JS::AddAssociatedMemory() is
  83  * no longer owned by a JSObject. Calls must match those to
  84  * AddAssociatedMemory().
  85  */
  86 extern JS_PUBLIC_API void RemoveAssociatedMemory(JSObject* obj, size_t nbytes,
  87                                                  MemoryUse use);
  88
  89 }  // namespace JS
  90
  91 #endif /* js_MemoryFunctions_h */