src/smalloc.h

   1 #ifndef SRC_SMALLOC_H_
   2 #define SRC_SMALLOC_H_
   3
   4 #include "node.h"
   5 #include "v8.h"
   6
   7 namespace node {
   8
   9 // Forward declaration
  10 class Environment;
  11
  12 /**
  13  * Simple memory allocator.
  14  *
  15  * Utilities for external memory allocation management. Is an abstraction for
  16  * v8's external array data handling to simplify and centralize how this is
  17  * managed.
  18  */
  19 namespace smalloc {
  20
  21 // mirrors deps/v8/src/objects.h
  22 static const unsigned int kMaxLength = 0x3fffffff;
  23
  24 NODE_EXTERN typedef void (*FreeCallback)(char* data, void* hint);
  25
  26 /**
  27  * Return byte size of external array type.
  28  */
  29 NODE_EXTERN size_t ExternalArraySize(enum v8::ExternalArrayType type);
  30
  31 /**
  32  * Allocate external array data onto obj.
  33  *
  34  * Passed data transfers ownership, and if no callback is passed then memory
  35  * will automatically be free'd using free() (not delete[]).
  36  *
  37  * length is always the byte size of the data. Not the length of the external
  38  * array. This intentionally differs from the JS API so users always know
  39  * exactly how much memory is being allocated, regardless of the external array
  40  * type. For this reason the helper function ExternalArraySize is provided to
  41  * help determine the appropriate byte size to be allocated.
  42  *
  43  * In the following example we're allocating a Float array and setting the
  44  * "length" property on the Object:
  45  *
  46  * \code
  47  *    size_t array_length = 8;
  48  *    size_t byte_length = node::smalloc::ExternalArraySize(
  49  *        v8::kExternalFloatArray);
  50  *    v8::Local<v8::Object> obj = v8::Object::New();
  51  *    char* data = static_cast<char*>(malloc(byte_length * array_length));
  52  *    node::smalloc::Alloc(env, obj, data, byte_length, v8::kExternalFloatArray);
  53  *    obj->Set(v8::String::NewFromUtf8("length"),
  54  *             v8::Integer::NewFromUnsigned(array_length));
  55  * \code
  56  */
  57 NODE_EXTERN void Alloc(Environment* env,
  58                        v8::Handle<v8::Object> obj,
  59                        size_t length,
  60                        enum v8::ExternalArrayType type =
  61                        v8::kExternalUnsignedByteArray);
  62 NODE_EXTERN void Alloc(Environment* env,
  63                        v8::Handle<v8::Object> obj,
  64                        char* data,
  65                        size_t length,
  66                        enum v8::ExternalArrayType type =
  67                        v8::kExternalUnsignedByteArray);
  68 NODE_EXTERN void Alloc(Environment* env,
  69                        v8::Handle<v8::Object> obj,
  70                        size_t length,
  71                        FreeCallback fn,
  72                        void* hint,
  73                        enum v8::ExternalArrayType type =
  74                        v8::kExternalUnsignedByteArray);
  75 NODE_EXTERN void Alloc(Environment* env,
  76                        v8::Handle<v8::Object> obj,
  77                        char* data,
  78                        size_t length,
  79                        FreeCallback fn,
  80                        void* hint,
  81                        enum v8::ExternalArrayType type =
  82                        v8::kExternalUnsignedByteArray);
  83
  84 /**
  85  * Free memory associated with an externally allocated object. If no external
  86  * memory is allocated to the object then nothing will happen.
  87  */
  88 NODE_EXTERN void AllocDispose(Environment* env, v8::Handle<v8::Object> obj);
  89
  90
  91 /**
  92  * Check if the Object has externally allocated memory.
  93  */
  94 NODE_EXTERN bool HasExternalData(Environment* env, v8::Local<v8::Object> obj);
  95
  96 }  // namespace smalloc
  97 }  // namespace node
  98
  99 #endif  // SRC_SMALLOC_H_