src/smalloc.h

   1 // Copyright Joyent, Inc. and other Node contributors.
   2 //
   3 // Permission is hereby granted, free of charge, to any person obtaining a
   4 // copy of this software and associated documentation files (the
   5 // "Software"), to deal in the Software without restriction, including
   6 // without limitation the rights to use, copy, modify, merge, publish,
   7 // distribute, sublicense, and/or sell copies of the Software, and to permit
   8 // persons to whom the Software is furnished to do so, subject to the
   9 // following conditions:
  10 //
  11 // The above copyright notice and this permission notice shall be included
  12 // in all copies or substantial portions of the Software.
  13 //
  14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
  17 // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
  18 // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  19 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
  21
  22 #ifndef SRC_SMALLOC_H_
  23 #define SRC_SMALLOC_H_
  24
  25 #include "node.h"
  26 #include "v8.h"
  27
  28 namespace node {
  29
  30 // Forward declaration
  31 class Environment;
  32
  33 /**
  34  * Simple memory allocator.
  35  *
  36  * Utilities for external memory allocation management. Is an abstraction for
  37  * v8's external array data handling to simplify and centralize how this is
  38  * managed.
  39  */
  40 namespace smalloc {
  41
  42 // mirrors deps/v8/src/objects.h
  43 static const unsigned int kMaxLength = 0x3fffffff;
  44
  45 NODE_EXTERN typedef void (*FreeCallback)(char* data, void* hint);
  46
  47 /**
  48  * Return byte size of external array type.
  49  */
  50 NODE_EXTERN size_t ExternalArraySize(enum v8::ExternalArrayType type);
  51
  52 /**
  53  * Allocate external array data onto obj.
  54  *
  55  * Passed data transfers ownership, and if no callback is passed then memory
  56  * will automatically be free'd using free() (not delete[]).
  57  *
  58  * length is always the byte size of the data. Not the length of the external
  59  * array. This intentionally differs from the JS API so users always know
  60  * exactly how much memory is being allocated, regardless of the external array
  61  * type. For this reason the helper function ExternalArraySize is provided to
  62  * help determine the appropriate byte size to be allocated.
  63  *
  64  * In the following example we're allocating a Float array and setting the
  65  * "length" property on the Object:
  66  *
  67  * \code
  68  *    size_t array_length = 8;
  69  *    size_t byte_length = node::smalloc::ExternalArraySize(
  70  *        v8::kExternalFloatArray);
  71  *    v8::Local<v8::Object> obj = v8::Object::New();
  72  *    char* data = static_cast<char*>(malloc(byte_length * array_length));
  73  *    node::smalloc::Alloc(obj, data, byte_length, v8::kExternalFloatArray);
  74  *    obj->Set(v8::String::NewFromUtf8("length"),
  75  *             v8::Integer::NewFromUnsigned(array_length));
  76  * \code
  77  */
  78 NODE_EXTERN void Alloc(Environment* env,
  79                        v8::Handle<v8::Object> obj,
  80                        size_t length,
  81                        enum v8::ExternalArrayType type =
  82                        v8::kExternalUnsignedByteArray);
  83 NODE_EXTERN void Alloc(Environment* env,
  84                        v8::Handle<v8::Object> obj,
  85                        char* data,
  86                        size_t length,
  87                        enum v8::ExternalArrayType type =
  88                        v8::kExternalUnsignedByteArray);
  89 NODE_EXTERN void Alloc(Environment* env,
  90                        v8::Handle<v8::Object> obj,
  91                        size_t length,
  92                        FreeCallback fn,
  93                        void* hint,
  94                        enum v8::ExternalArrayType type =
  95                        v8::kExternalUnsignedByteArray);
  96 NODE_EXTERN void Alloc(Environment* env,
  97                        v8::Handle<v8::Object> obj,
  98                        char* data,
  99                        size_t length,
 100                        FreeCallback fn,
 101                        void* hint,
 102                        enum v8::ExternalArrayType type =
 103                        v8::kExternalUnsignedByteArray);
 104
 105 /**
 106  * Free memory associated with an externally allocated object. If no external
 107  * memory is allocated to the object then nothing will happen.
 108  */
 109 NODE_EXTERN void AllocDispose(Environment* env, v8::Handle<v8::Object> obj);
 110
 111
 112 /**
 113  * Check if the Object has externally allocated memory.
 114  */
 115 NODE_EXTERN bool HasExternalData(Environment* env, v8::Local<v8::Object> obj);
 116
 117 }  // namespace smalloc
 118 }  // namespace node
 119
 120 #endif  // SRC_SMALLOC_H_