src/node_buffer.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 NODE_BUFFER_H_
  23 #define NODE_BUFFER_H_
  24
  25 #include <node.h>
  26 #include <node_object_wrap.h>
  27 #include <v8.h>
  28 #include <assert.h>
  29
  30 namespace node {
  31
  32 /* A buffer is a chunk of memory stored outside the V8 heap, mirrored by an
  33  * object in javascript. The object is not totally opaque, one can access
  34  * individual bytes with [] and slice it into substrings or sub-buffers
  35  * without copying memory.
  36  */
  37
  38 /*
  39    The C++ API for Buffer changed radically between v0.2 and v0.3, in fact
  40    it was the reason for bumping the version. In v0.2 JavaScript Buffers and
  41    C++ Buffers were in one-to-one correspondence via ObjectWrap. We found
  42    that it was faster to expose the C++ Buffers to JavaScript as a
  43    "SlowBuffer" which is used as a private backend to pure JavaScript
  44    "Buffer" objects - a 'Buffer' in v0.3 might look like this:
  45
  46    { _parent: s,
  47      _offset: 520,
  48      length: 5 }
  49
  50    Migrating code C++ Buffer code from v0.2 to v0.3 is difficult. Here are
  51    some tips:
  52     - buffer->data() calls should become Buffer::Data(buffer) calls.
  53     - buffer->length() calls should become Buffer::Length(buffer) calls.
  54     - There should not be any ObjectWrap::Unwrap<Buffer>() calls. You should
  55       not be storing pointers to Buffer objects at all - as they are
  56       now considered internal structures. Instead consider making a
  57       JavaScript reference to the buffer.
  58
  59    See the source code node-png as an example of a module which successfully
  60    compiles on both v0.2 and v0.3 while making heavy use of the C++ Buffer
  61    API.
  62
  63  */
  64
  65
  66 class Buffer : public ObjectWrap {
  67  public:
  68
  69   static bool HasInstance(v8::Handle<v8::Value> val);
  70
  71   static inline char* Data(v8::Handle<v8::Object> obj) {
  72     return (char*)obj->GetIndexedPropertiesExternalArrayData();
  73   }
  74
  75   static inline char* Data(Buffer *b) {
  76     return Buffer::Data(b->handle_);
  77   }
  78
  79   static inline size_t Length(v8::Handle<v8::Object> obj) {
  80     return (size_t)obj->GetIndexedPropertiesExternalArrayDataLength();
  81   }
  82
  83   static inline size_t Length(Buffer *b) {
  84     return Buffer::Length(b->handle_);
  85   }
  86
  87
  88   ~Buffer();
  89
  90   typedef void (*free_callback)(char *data, void *hint);
  91
  92   // C++ API for constructing fast buffer
  93   static v8::Handle<v8::Object> New(v8::Handle<v8::String> string);
  94
  95   static void Initialize(v8::Handle<v8::Object> target);
  96   static Buffer* New(size_t length); // public constructor
  97   static Buffer* New(char *data, size_t len); // public constructor
  98   static Buffer* New(char *data, size_t length,
  99                      free_callback callback, void *hint); // public constructor
 100
 101   private:
 102   static v8::Persistent<v8::FunctionTemplate> constructor_template;
 103
 104   static v8::Handle<v8::Value> New(const v8::Arguments &args);
 105   static v8::Handle<v8::Value> BinarySlice(const v8::Arguments &args);
 106   static v8::Handle<v8::Value> AsciiSlice(const v8::Arguments &args);
 107   static v8::Handle<v8::Value> Base64Slice(const v8::Arguments &args);
 108   static v8::Handle<v8::Value> Utf8Slice(const v8::Arguments &args);
 109   static v8::Handle<v8::Value> Ucs2Slice(const v8::Arguments &args);
 110   static v8::Handle<v8::Value> BinaryWrite(const v8::Arguments &args);
 111   static v8::Handle<v8::Value> Base64Write(const v8::Arguments &args);
 112   static v8::Handle<v8::Value> AsciiWrite(const v8::Arguments &args);
 113   static v8::Handle<v8::Value> Utf8Write(const v8::Arguments &args);
 114   static v8::Handle<v8::Value> Ucs2Write(const v8::Arguments &args);
 115   static v8::Handle<v8::Value> ByteLength(const v8::Arguments &args);
 116   static v8::Handle<v8::Value> MakeFastBuffer(const v8::Arguments &args);
 117   static v8::Handle<v8::Value> Fill(const v8::Arguments &args);
 118   static v8::Handle<v8::Value> Copy(const v8::Arguments &args);
 119
 120   Buffer(v8::Handle<v8::Object> wrapper, size_t length);
 121   void Replace(char *data, size_t length, free_callback callback, void *hint);
 122
 123   size_t length_;
 124   char* data_;
 125   free_callback callback_;
 126   void* callback_hint_;
 127 };
 128
 129
 130 }  // namespace node buffer
 131
 132 #endif  // NODE_BUFFER_H_