vnfmarket/src/main/webapp/vnfmarket/node_modules/nan/README.md

   1 Native Abstractions for Node.js
   2 ===============================
   3
   4 **A header file filled with macro and utility goodness for making add-on development for Node.js easier across versions 0.8, 0.10 and 0.11, and eventually 0.12.**
   5
   6 ***Current version: 1.0.0*** *(See [nan.h](https://github.com/rvagg/nan/blob/master/nan.h) for complete ChangeLog)*
   7
   8 [![NPM](https://nodei.co/npm/nan.png?downloads=true)](https://nodei.co/npm/nan/) [![NPM](https://nodei.co/npm-dl/nan.png?months=6)](https://nodei.co/npm/nan/)
   9
  10 Thanks to the crazy changes in V8 (and some in Node core), keeping native addons compiling happily across versions, particularly 0.10 to 0.11/0.12, is a minor nightmare. The goal of this project is to store all logic necessary to develop native Node.js addons without having to inspect `NODE_MODULE_VERSION` and get yourself into a macro-tangle.
  11
  12 This project also contains some helper utilities that make addon development a bit more pleasant.
  13
  14  * **[News & Updates](#news)**
  15  * **[Usage](#usage)**
  16  * **[Example](#example)**
  17  * **[API](#api)**
  18
  19 <a name="news"></a>
  20 ## News & Updates
  21
  22 ### May-2013: Major changes for V8 3.25 / Node 0.11.13
  23
  24 Node 0.11.11 and 0.11.12 were both broken releases for native add-ons, you simply can't properly compile against either of them for different reasons. But we now have a 0.11.13 release that jumps a couple of versions of V8 ahead and includes some more, major (traumatic) API changes.
  25
  26 Because we are now nearing Node 0.12 and estimate that the version of V8 we are using in Node 0.11.13 will be close to the API we get for 0.12, we have taken the opportunity to not only *fix* NAN for 0.11.13 but make some major changes to improve the NAN API.
  27
  28 We have **removed support for Node 0.11 versions prior to 0.11.13**, (although our tests are still passing for 0.11.10). As usual, our tests are run against (and pass) the last 5 versions of Node 0.8 and Node 0.10. We also include Node 0.11.13 obviously.
  29
  30 The major change is something that [Benjamin Byholm](kkoopa) has put many hours in to. We now have a fantastic new `NanNew<T>(args)` interface for creating new `Local`s, this replaces `NanNewLocal()` and much more. If you look in [./nan.h](nan.h) you'll see a large number of overloaded versions of this method. In general you should be able to `NanNew<Type>(arguments)` for any type you want to make a `Local` from. This includes `Persistent` types, so we now have a `Local<T> NanNew(const Persistent<T> arg)` to replace `NanPersistentToLocal()`.
  31
  32 We also now have `NanUndefined()`, `NanNull()`, `NanTrue()` and `NanFalse()`. Mainly because of the new requirement for an `Isolate` argument for each of the native V8 versions of this.
  33
  34 V8 has now introduced an `EscapableHandleScope` from which you `scope.Escape(Local<T> value)` to *return* a value from a one scope to another. This replaces the standard `HandleScope` and `scope.Close(Local<T> value)`, although `HandleScope` still exists for when you don't need to return a handle to the caller. For NAN we are exposing it as `NanEscapableScope()` and `NanEscapeScope()`, while `NanScope()` is still how you create a new scope that doesn't need to return handles. For older versions of Node/V8, it'll still map to the older `HandleScope` functionality.
  35
  36 `NanFromV8String()` was deprecated and has now been removed. You should use `NanCString()` or `NanRawString()` instead.
  37
  38 Because `node::MakeCallback()` now takes an `Isolate`, and because it doesn't exist in older versions of Node, we've introduced `NanMakeCallabck()`. You should *always* use this when calling a JavaScript function from C++.
  39
  40 There's lots more, check out the Changelog in nan.h or look through [#86](https://github.com/rvagg/nan/pull/86) for all the gory details.
  41
  42 ### Dec-2013: NanCString and NanRawString
  43
  44 Two new functions have been introduced to replace the functionality that's been provided by `NanFromV8String` until now. NanCString has sensible defaults so it's super easy to fetch a null-terminated c-style string out of a `v8::String`. `NanFromV8String` is still around and has defaults that allow you to pass a single handle to fetch a `char*` while `NanRawString` requires a little more attention to arguments.
  45
  46 ### Nov-2013: Node 0.11.9+ breaking V8 change
  47
  48 The version of V8 that's shipping with Node 0.11.9+ has changed the signature for new `Local`s to: `v8::Local<T>::New(isolate, value)`, i.e. introducing the `isolate` argument and therefore breaking all new `Local` declarations for previous versions. NAN 0.6+ now includes a `NanNewLocal<T>(value)` that can be used in place to work around this incompatibility and maintain compatibility with 0.8->0.11.9+ (minus a few early 0.11 releases).
  49
  50 For example, if you wanted to return a `null` on a callback you will have to change the argument from `v8::Local<v8::Value>::New(v8::Null())` to `NanNewLocal<v8::Value>(v8::Null())`.
  51
  52 ### Nov-2013: Change to binding.gyp `"include_dirs"` for NAN
  53
  54 Inclusion of NAN in a project's binding.gyp is now greatly simplified. You can now just use `"<!(node -e \"require('nan')\")"` in your `"include_dirs"`, see example below (note Windows needs the quoting around `require` to be just right: `"require('nan')"` with appropriate `\` escaping).
  55
  56 <a name="usage"></a>
  57 ## Usage
  58
  59 Simply add **NAN** as a dependency in the *package.json* of your Node addon:
  60
  61 ``` bash
  62 $ npm install --save nan
  63 ```
  64
  65 Pull in the path to **NAN** in your *binding.gyp* so that you can use `#include <nan.h>` in your *.cpp* files:
  66
  67 ``` python
  68 "include_dirs" : [
  69     "<!(node -e \"require('nan')\")"
  70 ]
  71 ```
  72
  73 This works like a `-I<path-to-NAN>` when compiling your addon.
  74
  75 <a name="example"></a>
  76 ## Example
  77
  78 See **[LevelDOWN](https://github.com/rvagg/node-leveldown/pull/48)** for a full example of **NAN** in use.
  79
  80 For a simpler example, see the **[async pi estimation example](https://github.com/rvagg/nan/tree/master/examples/async_pi_estimate)** in the examples directory for full code and an explanation of what this Monte Carlo Pi estimation example does. Below are just some parts of the full example that illustrate the use of **NAN**.
  81
  82 Compare to the current 0.10 version of this example, found in the [node-addon-examples](https://github.com/rvagg/node-addon-examples/tree/master/9_async_work) repository and also a 0.11 version of the same found [here](https://github.com/kkoopa/node-addon-examples/tree/5c01f58fc993377a567812597e54a83af69686d7/9_async_work).
  83
  84 Note that there is no embedded version sniffing going on here and also the async work is made much simpler, see below for details on the `NanAsyncWorker` class.
  85
  86 ```c++
  87 // addon.cc
  88 #include <node.h>
  89 #include <nan.h>
  90 // ...
  91
  92 using v8::FunctionTemplate;
  93 using v8::Handle;
  94 using v8::Object;
  95
  96 void InitAll(Handle<Object> exports) {
  97   exports->Set(NanSymbol("calculateSync"),
  98     NanNew<FunctionTemplate>(CalculateSync)->GetFunction());
  99
 100   exports->Set(NanSymbol("calculateAsync"),
 101     NanNew<FunctionTemplate>(CalculateAsync)->GetFunction());
 102 }
 103
 104 NODE_MODULE(addon, InitAll)
 105 ```
 106
 107 ```c++
 108 // sync.h
 109 #include <node.h>
 110 #include <nan.h>
 111
 112 NAN_METHOD(CalculateSync);
 113 ```
 114
 115 ```c++
 116 // sync.cc
 117 #include <node.h>
 118 #include <nan.h>
 119 #include "./sync.h"
 120 // ...
 121
 122 using v8::Number;
 123
 124 // Simple synchronous access to the `Estimate()` function
 125 NAN_METHOD(CalculateSync) {
 126   NanScope();
 127
 128   // expect a number as the first argument
 129   int points = args[0]->Uint32Value();
 130   double est = Estimate(points);
 131
 132   NanReturnValue(NanNew<Number>(est));
 133 }
 134 ```
 135
 136 ```c++
 137 // async.cc
 138 #include <node.h>
 139 #include <nan.h>
 140 #include "./async.h"
 141
 142 // ...
 143
 144 using v8::Function;
 145 using v8::Local;
 146 using v8::Null;
 147 using v8::Number;
 148 using v8::Value;
 149
 150 class PiWorker : public NanAsyncWorker {
 151  public:
 152   PiWorker(NanCallback *callback, int points)
 153     : NanAsyncWorker(callback), points(points) {}
 154   ~PiWorker() {}
 155
 156   // Executed inside the worker-thread.
 157   // It is not safe to access V8, or V8 data structures
 158   // here, so everything we need for input and output
 159   // should go on `this`.
 160   void Execute () {
 161     estimate = Estimate(points);
 162   }
 163
 164   // Executed when the async work is complete
 165   // this function will be run inside the main event loop
 166   // so it is safe to use V8 again
 167   void HandleOKCallback () {
 168     NanScope();
 169
 170     Local<Value> argv[] = {
 171         NanNew(NanNull())
 172       , NanNew<Number>(estimate)
 173     };
 174
 175     callback->Call(2, argv);
 176   };
 177
 178  private:
 179   int points;
 180   double estimate;
 181 };
 182
 183 // Asynchronous access to the `Estimate()` function
 184 NAN_METHOD(CalculateAsync) {
 185   NanScope();
 186
 187   int points = args[0]->Uint32Value();
 188   NanCallback *callback = new NanCallback(args[1].As<Function>());
 189
 190   NanAsyncQueueWorker(new PiWorker(callback, points));
 191   NanReturnUndefined();
 192 }
 193 ```
 194
 195 <a name="api"></a>
 196 ## API
 197
 198  * <a href="#api_nan_method"><b><code>NAN_METHOD</code></b></a>
 199  * <a href="#api_nan_getter"><b><code>NAN_GETTER</code></b></a>
 200  * <a href="#api_nan_setter"><b><code>NAN_SETTER</code></b></a>
 201  * <a href="#api_nan_property_getter"><b><code>NAN_PROPERTY_GETTER</code></b></a>
 202  * <a href="#api_nan_property_setter"><b><code>NAN_PROPERTY_SETTER</code></b></a>
 203  * <a href="#api_nan_property_enumerator"><b><code>NAN_PROPERTY_ENUMERATOR</code></b></a>
 204  * <a href="#api_nan_property_deleter"><b><code>NAN_PROPERTY_DELETER</code></b></a>
 205  * <a href="#api_nan_property_query"><b><code>NAN_PROPERTY_QUERY</code></b></a>
 206  * <a href="#api_nan_index_getter"><b><code>NAN_INDEX_GETTER</code></b></a>
 207  * <a href="#api_nan_index_setter"><b><code>NAN_INDEX_SETTER</code></b></a>
 208  * <a href="#api_nan_index_enumerator"><b><code>NAN_INDEX_ENUMERATOR</code></b></a>
 209  * <a href="#api_nan_index_deleter"><b><code>NAN_INDEX_DELETER</code></b></a>
 210  * <a href="#api_nan_index_query"><b><code>NAN_INDEX_QUERY</code></b></a>
 211  * <a href="#api_nan_weak_callback"><b><code>NAN_WEAK_CALLBACK</code></b></a>
 212  * <a href="#api_nan_deprecated"><b><code>NAN_DEPRECATED</code></b></a>
 213  * <a href="#api_nan_inline"><b><code>NAN_INLINE</code></b></a>
 214  * <a href="#api_nan_new"><b><code>NanNew</code></b></a>
 215  * <a href="#api_nan_undefined"><b><code>NanUndefined</code></b></a>
 216  * <a href="#api_nan_null"><b><code>NanNull</code></b></a>
 217  * <a href="#api_nan_true"><b><code>NanTrue</code></b></a>
 218  * <a href="#api_nan_false"><b><code>NanFalse</code></b></a>
 219  * <a href="#api_nan_return_value"><b><code>NanReturnValue</code></b></a>
 220  * <a href="#api_nan_return_undefined"><b><code>NanReturnUndefined</code></b></a>
 221  * <a href="#api_nan_return_null"><b><code>NanReturnNull</code></b></a>
 222  * <a href="#api_nan_return_empty_string"><b><code>NanReturnEmptyString</code></b></a>
 223  * <a href="#api_nan_scope"><b><code>NanScope</code></b></a>
 224  * <a href="#api_nan_escapable_scope"><b><code>NanEscapableScope</code></b></a>
 225  * <a href="#api_nan_escape_scope"><b><code>NanEscapeScope</code></b></a>
 226  * <a href="#api_nan_locker"><b><code>NanLocker</code></b></a>
 227  * <a href="#api_nan_unlocker"><b><code>NanUnlocker</code></b></a>
 228  * <a href="#api_nan_get_internal_field_pointer"><b><code>NanGetInternalFieldPointer</code></b></a>
 229  * <a href="#api_nan_set_internal_field_pointer"><b><code>NanSetInternalFieldPointer</code></b></a>
 230  * <a href="#api_nan_object_wrap_handle"><b><code>NanObjectWrapHandle</code></b></a>
 231  * <a href="#api_nan_symbol"><b><code>NanSymbol</code></b></a>
 232  * <a href="#api_nan_get_pointer_safe"><b><code>NanGetPointerSafe</code></b></a>
 233  * <a href="#api_nan_set_pointer_safe"><b><code>NanSetPointerSafe</code></b></a>
 234  * <a href="#api_nan_raw_string"><b><code>NanRawString</code></b></a>
 235  * <a href="#api_nan_c_string"><b><code>NanCString</code></b></a>
 236  * <a href="#api_nan_boolean_option_value"><b><code>NanBooleanOptionValue</code></b></a>
 237  * <a href="#api_nan_uint32_option_value"><b><code>NanUInt32OptionValue</code></b></a>
 238  * <a href="#api_nan_error"><b><code>NanError</code></b>, <b><code>NanTypeError</code></b>, <b><code>NanRangeError</code></b></a>
 239  * <a href="#api_nan_throw_error"><b><code>NanThrowError</code></b>, <b><code>NanThrowTypeError</code></b>, <b><code>NanThrowRangeError</code></b>, <b><code>NanThrowError(Handle<Value>)</code></b>, <b><code>NanThrowError(Handle<Value>, int)</code></b></a>
 240  * <a href="#api_nan_new_buffer_handle"><b><code>NanNewBufferHandle(char *, size_t, FreeCallback, void *)</code></b>, <b><code>NanNewBufferHandle(char *, uint32_t)</code></b>, <b><code>NanNewBufferHandle(uint32_t)</code></b></a>
 241  * <a href="#api_nan_buffer_use"><b><code>NanBufferUse(char *, uint32_t)</code></b></a>
 242  * <a href="#api_nan_new_context_handle"><b><code>NanNewContextHandle</code></b></a>
 243  * <a href="#api_nan_get_current_context"><b><code>NanGetCurrentContext</code></b></a>
 244  * <a href="#api_nan_has_instance"><b><code>NanHasInstance</code></b></a>
 245  * <a href="#api_nan_dispose_persistent"><b><code>NanDisposePersistent</code></b></a>
 246  * <a href="#api_nan_assign_persistent"><b><code>NanAssignPersistent</code></b></a>
 247  * <a href="#api_nan_make_weak_persistent"><b><code>NanMakeWeakPersistent</code></b></a>
 248  * <a href="#api_nan_set_template"><b><code>NanSetTemplate</code></b></a>
 249  * <a href="#api_nan_make_callback"><b><code>NanMakeCallback</code></b></a>
 250  * <a href="#api_nan_compile_script"><b><code>NanCompileScript</code></b></a>
 251  * <a href="#api_nan_run_script"><b><code>NanRunScript</code></b></a>
 252  * <a href="#api_nan_adjust_external_memory"><b><code>NanAdjustExternalMemory</code></b></a>
 253  * <a href="#api_nan_add_gc_epilogue_callback"><b><code>NanAddGCEpilogueCallback</code></b></a>
 254  * <a href="#api_nan_add_gc_prologue_callback"><b><code>NanAddGCPrologueCallback</code></b></a>
 255  * <a href="#api_nan_remove_gc_epilogue_callback"><b><code>NanRemoveGCEpilogueCallback</code></b></a>
 256  * <a href="#api_nan_remove_gc_prologue_callback"><b><code>NanRemoveGCPrologueCallback</code></b></a>
 257  * <a href="#api_nan_get_heap_statistics"><b><code>NanGetHeapStatistics</code></b></a>
 258  * <a href="#api_nan_callback"><b><code>NanCallback</code></b></a>
 259  * <a href="#api_nan_async_worker"><b><code>NanAsyncWorker</code></b></a>
 260  * <a href="#api_nan_async_queue_worker"><b><code>NanAsyncQueueWorker</code></b></a>
 261
 262 <a name="api_nan_method"></a>
 263 ### NAN_METHOD(methodname)
 264
 265 Use `NAN_METHOD` to define your V8 accessible methods:
 266
 267 ```c++
 268 // .h:
 269 class Foo : public node::ObjectWrap {
 270   ...
 271
 272   static NAN_METHOD(Bar);
 273   static NAN_METHOD(Baz);
 274 }
 275
 276
 277 // .cc:
 278 NAN_METHOD(Foo::Bar) {
 279   ...
 280 }
 281
 282 NAN_METHOD(Foo::Baz) {
 283   ...
 284 }
 285 ```
 286
 287 The reason for this macro is because of the method signature change in 0.11:
 288
 289 ```c++
 290 // 0.10 and below:
 291 Handle<Value> name(const Arguments& args)
 292
 293 // 0.11 and above
 294 void name(const FunctionCallbackInfo<Value>& args)
 295 ```
 296
 297 The introduction of `FunctionCallbackInfo` brings additional complications:
 298
 299 <a name="api_nan_getter"></a>
 300 ### NAN_GETTER(methodname)
 301
 302 Use `NAN_GETTER` to declare your V8 accessible getters. You get a `Local<String>` `property` and an appropriately typed `args` object that can act like the `args` argument to a `NAN_METHOD` call.
 303
 304 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_GETTER`.
 305
 306 <a name="api_nan_setter"></a>
 307 ### NAN_SETTER(methodname)
 308
 309 Use `NAN_SETTER` to declare your V8 accessible setters. Same as `NAN_GETTER` but you also get a `Local<Value>` `value` object to work with.
 310
 311 <a name="api_nan_property_getter"></a>
 312 ### NAN_PROPERTY_GETTER(cbname)
 313 Use `NAN_PROPERTY_GETTER` to declare your V8 accessible property getters. You get a `Local<String>` `property` and an appropriately typed `args` object that can act similar to the `args` argument to a `NAN_METHOD` call.
 314
 315 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_GETTER`.
 316
 317 <a name="api_nan_property_setter"></a>
 318 ### NAN_PROPERTY_SETTER(cbname)
 319 Use `NAN_PROPERTY_SETTER` to declare your V8 accessible property setters. Same as `NAN_PROPERTY_GETTER` but you also get a `Local<Value>` `value` object to work with.
 320
 321 <a name="api_nan_property_enumerator"></a>
 322 ### NAN_PROPERTY_ENUMERATOR(cbname)
 323 Use `NAN_PROPERTY_ENUMERATOR` to declare your V8 accessible property enumerators. You get an appropriately typed `args` object like the `args` argument to a `NAN_PROPERTY_GETTER` call.
 324
 325 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_ENUMERATOR`.
 326
 327 <a name="api_nan_property_deleter"></a>
 328 ### NAN_PROPERTY_DELETER(cbname)
 329 Use `NAN_PROPERTY_DELETER` to declare your V8 accessible property deleters. Same as `NAN_PROPERTY_GETTER`.
 330
 331 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_DELETER`.
 332
 333 <a name="api_nan_property_query"></a>
 334 ### NAN_PROPERTY_QUERY(cbname)
 335 Use `NAN_PROPERTY_QUERY` to declare your V8 accessible property queries. Same as `NAN_PROPERTY_GETTER`.
 336
 337 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_QUERY`.
 338
 339 <a name="api_nan_index_getter"></a>
 340 ### NAN_INDEX_GETTER(cbname)
 341 Use `NAN_INDEX_GETTER` to declare your V8 accessible index getters. You get a `uint32_t` `index` and an appropriately typed `args` object that can act similar to the `args` argument to a `NAN_METHOD` call.
 342
 343 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_INDEX_GETTER`.
 344
 345 <a name="api_nan_index_setter"></a>
 346 ### NAN_INDEX_SETTER(cbname)
 347 Use `NAN_INDEX_SETTER` to declare your V8 accessible index setters. Same as `NAN_INDEX_GETTER` but you also get a `Local<Value>` `value` object to work with.
 348
 349 <a name="api_nan_index_enumerator"></a>
 350 ### NAN_INDEX_ENUMERATOR(cbname)
 351 Use `NAN_INDEX_ENUMERATOR` to declare your V8 accessible index enumerators. You get an appropriately typed `args` object like the `args` argument to a `NAN_INDEX_GETTER` call.
 352
 353 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_INDEX_ENUMERATOR`.
 354
 355 <a name="api_nan_index_deleter"></a>
 356 ### NAN_INDEX_DELETER(cbname)
 357 Use `NAN_INDEX_DELETER` to declare your V8 accessible index deleters. Same as `NAN_INDEX_GETTER`.
 358
 359 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_INDEX_DELETER`.
 360
 361 <a name="api_nan_index_query"></a>
 362 ### NAN_INDEX_QUERY(cbname)
 363 Use `NAN_INDEX_QUERY` to declare your V8 accessible index queries. Same as `NAN_INDEX_GETTER`.
 364
 365 You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_INDEX_QUERY`.
 366
 367 <a name="api_nan_weak_callback"></a>
 368 ### NAN_WEAK_CALLBACK(cbname)
 369
 370 Use `NAN_WEAK_CALLBACK` to define your V8 WeakReference callbacks. Do not use for declaration. There is an argument object `const _NanWeakCallbackData<T, P> &data` allowing access to the weak object and the supplied parameter through its `GetValue` and `GetParameter` methods.
 371
 372 ```c++
 373 NAN_WEAK_CALLBACK(weakCallback) {
 374   int *parameter = data.GetParameter();
 375   NanMakeCallback(NanGetCurrentContext()->Global(), data.GetValue(), 0, NULL);
 376   if ((*parameter)++ == 0) {
 377     data.Revive();
 378   } else {
 379     delete parameter;
 380     data.Dispose();
 381   }
 382 }
 383 ```
 384
 385 <a name="api_nan_deprecated"></a>
 386 ### NAN_DEPRECATED
 387 Declares a function as deprecated.
 388
 389 ```c++
 390 static NAN_DEPRECATED NAN_METHOD(foo) {
 391   ...
 392 }
 393 ```
 394
 395 <a name="api_nan_inline"></a>
 396 ### NAN_INLINE
 397 Inlines a function.
 398
 399 ```c++
 400 NAN_INLINE int foo(int bar) {
 401   ...
 402 }
 403 ```
 404
 405 <a name="api_nan_new"></a>
 406 ### Local&lt;T&gt; NanNew&lt;T&gt;( ... )
 407
 408 Use `NanNew` to construct almost all v8 objects and make new local handles.
 409
 410 ```c++
 411 Local<String> s = NanNew<String>("value");
 412
 413 ...
 414
 415 Persistent<Object> o;
 416
 417 ...
 418
 419 Local<Object> lo = NanNew(o);
 420
 421 ```
 422
 423 <a name="api_nan_undefined"></a>
 424 ### Handle&lt;Primitive&gt; NanUndefined()
 425
 426 Use instead of `Undefined()`
 427
 428 <a name="api_nan_null"></a>
 429 ### Handle&lt;Primitive&gt; NanNull()
 430
 431 Use instead of `Null()`
 432
 433 <a name="api_nan_true"></a>
 434 ### Handle&lt;Primitive&gt; NanTrue()
 435
 436 Use instead of `True()`
 437
 438 <a name="api_nan_false"></a>
 439 ### Handle&lt;Primitive&gt; NanFalse()
 440
 441 Use instead of `False()`
 442
 443 <a name="api_nan_return_value"></a>
 444 ### NanReturnValue(Handle&lt;Value&gt;)
 445
 446 Use `NanReturnValue` when you want to return a value from your V8 accessible method:
 447
 448 ```c++
 449 NAN_METHOD(Foo::Bar) {
 450   ...
 451
 452   NanReturnValue(NanNew<String>("FooBar!"));
 453 }
 454 ```
 455
 456 No `return` statement required.
 457
 458 <a name="api_nan_return_undefined"></a>
 459 ### NanReturnUndefined()
 460
 461 Use `NanReturnUndefined` when you don't want to return anything from your V8 accessible method:
 462
 463 ```c++
 464 NAN_METHOD(Foo::Baz) {
 465   ...
 466
 467   NanReturnUndefined();
 468 }
 469 ```
 470
 471 <a name="api_nan_return_null"></a>
 472 ### NanReturnNull()
 473
 474 Use `NanReturnNull` when you want to return `Null` from your V8 accessible method:
 475
 476 ```c++
 477 NAN_METHOD(Foo::Baz) {
 478   ...
 479
 480   NanReturnNull();
 481 }
 482 ```
 483
 484 <a name="api_nan_return_empty_string"></a>
 485 ### NanReturnEmptyString()
 486
 487 Use `NanReturnEmptyString` when you want to return an empty `String` from your V8 accessible method:
 488
 489 ```c++
 490 NAN_METHOD(Foo::Baz) {
 491   ...
 492
 493   NanReturnEmptyString();
 494 }
 495 ```
 496
 497 <a name="api_nan_scope"></a>
 498 ### NanScope()
 499
 500 The introduction of `isolate` references for many V8 calls in Node 0.11 makes `NanScope()` necessary, use it in place of `HandleScope scope`:
 501
 502 ```c++
 503 NAN_METHOD(Foo::Bar) {
 504   NanScope();
 505
 506   NanReturnValue(NanNew<String>("FooBar!"));
 507 }
 508 ```
 509
 510 <a name="api_nan_escapable_scope"></a>
 511 ### NanEscapableScope()
 512
 513 The separation of handle scopes into escapable and inescapable scopes makes `NanEscapableScope()` necessary, use it in place of `HandleScope scope` when you later wish to `Close()` the scope:
 514
 515 ```c++
 516 Handle<String> Foo::Bar() {
 517   NanEscapableScope();
 518
 519   return NanEscapeScope(NanNew<String>("FooBar!"));
 520 }
 521 ```
 522
 523 <a name="api_nan_esacpe_scope"></a>
 524 ### Local&lt;T&gt; NanEscapeScope(Handle&lt;T&gt; value);
 525 Use together with `NanEscapableScope` to escape the scope. Corresponds to `HandleScope::Close` or `EscapableHandleScope::Escape`.
 526
 527 <a name="api_nan_locker"></a>
 528 ### NanLocker()
 529
 530 The introduction of `isolate` references for many V8 calls in Node 0.11 makes `NanLocker()` necessary, use it in place of `Locker locker`:
 531
 532 ```c++
 533 NAN_METHOD(Foo::Bar) {
 534   NanLocker();
 535   ...
 536   NanUnlocker();
 537 }
 538 ```
 539
 540 <a name="api_nan_unlocker"></a>
 541 ### NanUnlocker()
 542
 543 The introduction of `isolate` references for many V8 calls in Node 0.11 makes `NanUnlocker()` necessary, use it in place of `Unlocker unlocker`:
 544
 545 ```c++
 546 NAN_METHOD(Foo::Bar) {
 547   NanLocker();
 548   ...
 549   NanUnlocker();
 550 }
 551 ```
 552
 553 <a name="api_nan_get_internal_field_pointer"></a>
 554 ### void * NanGetInternalFieldPointer(Handle&lt;Object&gt;, int)
 555
 556 Gets a pointer to the internal field with at `index` from a V8 `Object` handle.
 557
 558 ```c++
 559 Local<Object> obj;
 560 ...
 561 NanGetInternalFieldPointer(obj, 0);
 562 ```
 563 <a name="api_nan_set_internal_field_pointer"></a>
 564 ### void NanSetInternalFieldPointer(Handle&lt;Object&gt;, int, void *)
 565
 566 Sets the value of the internal field at `index` on a V8 `Object` handle.
 567
 568 ```c++
 569 static Persistent<Function> dataWrapperCtor;
 570 ...
 571 Local<Object> wrapper = NanPersistentToLocal(dataWrapperCtor)->NewInstance();
 572 NanSetInternalFieldPointer(wrapper, 0, this);
 573 ```
 574
 575 <a name="api_nan_object_wrap_handle"></a>
 576 ### Local&lt;Object&gt; NanObjectWrapHandle(Object)
 577
 578 When you want to fetch the V8 object handle from a native object you've wrapped with Node's `ObjectWrap`, you should use `NanObjectWrapHandle`:
 579
 580 ```c++
 581 NanObjectWrapHandle(iterator)->Get(NanSymbol("end"))
 582 ```
 583
 584 <a name="api_nan_symbol"></a>
 585 ### String NanSymbol(char *)
 586
 587 Use to create string symbol objects (i.e. `v8::String::NewSymbol(x)`), for getting and setting object properties, or names of objects.
 588
 589 ```c++
 590 bool foo = false;
 591 if (obj->Has(NanSymbol("foo")))
 592   foo = optionsObj->Get(NanSymbol("foo"))->BooleanValue()
 593 ```
 594
 595 <a name="api_nan_get_pointer_safe"></a>
 596 ### Type NanGetPointerSafe(Type *[, Type])
 597
 598 A helper for getting values from optional pointers. If the pointer is `NULL`, the function returns the optional default value, which defaults to `0`.  Otherwise, the function returns the value the pointer points to.
 599
 600 ```c++
 601 char *plugh(uint32_t *optional) {
 602   char res[] = "xyzzy";
 603   uint32_t param = NanGetPointerSafe<uint32_t>(optional, 0x1337);
 604   switch (param) {
 605     ...
 606   }
 607   NanSetPointerSafe<uint32_t>(optional, 0xDEADBEEF);
 608 }
 609 ```
 610
 611 <a name="api_nan_set_pointer_safe"></a>
 612 ### bool NanSetPointerSafe(Type *, Type)
 613
 614 A helper for setting optional argument pointers. If the pointer is `NULL`, the function simply returns `false`.  Otherwise, the value is assigned to the variable the pointer points to.
 615
 616 ```c++
 617 const char *plugh(size_t *outputsize) {
 618   char res[] = "xyzzy";
 619   if !(NanSetPointerSafe<size_t>(outputsize, strlen(res) + 1)) {
 620     ...
 621   }
 622
 623   ...
 624 }
 625 ```
 626
 627 <a name="api_nan_raw_string"></a>
 628 ### void* NanRawString(Handle&lt;Value&gt;, enum Nan::Encoding, size_t *, void *, size_t, int)
 629
 630 When you want to convert a V8 `String` to a `char*` buffer, use `NanRawString`. You have to supply an encoding as well as a pointer to a variable that will be assigned the number of bytes in the returned string. It is also possible to supply a buffer and its length to the function in order not to have a new buffer allocated. The final argument allows setting `String::WriteOptions`.
 631 Just remember that you'll end up with an object that you'll need to `delete[]` at some point unless you supply your own buffer:
 632
 633 ```c++
 634 size_t count;
 635 void* decoded = NanRawString(args[1], Nan::BASE64, &count, NULL, 0, String::HINT_MANY_WRITES_EXPECTED);
 636 char param_copy[count];
 637 memcpy(param_copy, decoded, count);
 638 delete[] decoded;
 639 ```
 640
 641 <a name="api_nan_c_string"></a>
 642 ### char* NanCString(Handle&lt;Value&gt;, size_t *[, char *, size_t, int])
 643
 644 When you want to convert a V8 `String` to a null-terminated C `char*` use `NanCString`. The resulting `char*` will be UTF-8-encoded, and you need to supply a pointer to a variable that will be assigned the number of bytes in the returned string. It is also possible to supply a buffer and its length to the function in order not to have a new buffer allocated. The final argument allows optionally setting `String::WriteOptions`, which default to `v8::String::NO_OPTIONS`.
 645 Just remember that you'll end up with an object that you'll need to `delete[]` at some point unless you supply your own buffer:
 646
 647 ```c++
 648 size_t count;
 649 char* name = NanCString(args[0], &count);
 650 ```
 651
 652 <a name="api_nan_boolean_option_value"></a>
 653 ### bool NanBooleanOptionValue(Handle&lt;Value&gt;, Handle&lt;String&gt;[, bool])
 654
 655 When you have an "options" object that you need to fetch properties from, boolean options can be fetched with this pair. They check first if the object exists (`IsEmpty`), then if the object has the given property (`Has`) then they get and convert/coerce the property to a `bool`.
 656
 657 The optional last parameter is the *default* value, which is `false` if left off:
 658
 659 ```c++
 660 // `foo` is false unless the user supplies a truthy value for it
 661 bool foo = NanBooleanOptionValue(optionsObj, NanSymbol("foo"));
 662 // `bar` is true unless the user supplies a falsy value for it
 663 bool bar = NanBooleanOptionValueDefTrue(optionsObj, NanSymbol("bar"), true);
 664 ```
 665
 666 <a name="api_nan_uint32_option_value"></a>
 667 ### uint32_t NanUInt32OptionValue(Handle&lt;Value&gt;, Handle&lt;String&gt;, uint32_t)
 668
 669 Similar to `NanBooleanOptionValue`, use `NanUInt32OptionValue` to fetch an integer option from your options object. Can be any kind of JavaScript `Number` and it will be coerced to an unsigned 32-bit integer.
 670
 671 Requires all 3 arguments as a default is not optional:
 672
 673 ```c++
 674 uint32_t count = NanUInt32OptionValue(optionsObj, NanSymbol("count"), 1024);
 675 ```
 676
 677 <a name="api_nan_error"></a>
 678 ### NanError(message), NanTypeError(message), NanRangeError(message)
 679
 680 For making `Error`, `TypeError` and `RangeError` objects.
 681
 682 ```c++
 683 Local<Value> res = NanError("you must supply a callback argument");
 684 ```
 685
 686 <a name="api_nan_throw_error"></a>
 687 ### NanThrowError(message), NanThrowTypeError(message), NanThrowRangeError(message), NanThrowError(Local&lt;Value&gt;), NanThrowError(Local&lt;Value&gt;, int)
 688
 689 For throwing `Error`, `TypeError` and `RangeError` objects. You should `return` this call:
 690
 691 ```c++
 692 return NanThrowError("you must supply a callback argument");
 693 ```
 694
 695 Can also handle any custom object you may want to throw. If used with the error code argument, it will add the supplied error code to the error object as a property called `code`.
 696
 697 <a name="api_nan_new_buffer_handle"></a>
 698 ### Local&lt;Object&gt; NanNewBufferHandle(char *, uint32_t), Local&lt;Object&gt; NanNewBufferHandle(uint32_t)
 699
 700 The `Buffer` API has changed a little in Node 0.11, this helper provides consistent access to `Buffer` creation:
 701
 702 ```c++
 703 NanNewBufferHandle((char*)value.data(), value.size());
 704 ```
 705
 706 Can also be used to initialize a `Buffer` with just a `size` argument.
 707
 708 Can also be supplied with a `NanFreeCallback` and a hint for the garbage collector.
 709
 710 <a name="api_nan_buffer_use"></a>
 711 ### Local&lt;Object&gt; NanBufferUse(char*, uint32_t)
 712
 713 `Buffer::New(char*, uint32_t)` prior to 0.11 would make a copy of the data.
 714 While it was possible to get around this, it required a shim by passing a
 715 callback. So the new API `Buffer::Use(char*, uint32_t)` was introduced to remove
 716 needing to use this shim.
 717
 718 `NanBufferUse` uses the `char*` passed as the backing data, and will free the
 719 memory automatically when the weak callback is called. Keep this in mind, as
 720 careless use can lead to "double free or corruption" and other cryptic failures.
 721
 722 <a name="api_nan_has_instance"></a>
 723 ### bool NanHasInstance(Persistent&lt;FunctionTemplate&gt;&, Handle&lt;Value&gt;)
 724
 725 Can be used to check the type of an object to determine it is of a particular class you have already defined and have a `Persistent<FunctionTemplate>` handle for.
 726
 727 <a href="#api_nan_new_context_handle">
 728 ### Local&lt;Context&gt; NanNewContextHandle([ExtensionConfiguration*, Handle&lt;ObjectTemplate&gt;, Handle&lt;Value&gt;])
 729 Creates a new `Local<Context>` handle.
 730
 731 ```c++
 732 Local<FunctionTemplate> ftmpl = NanNew<FunctionTemplate>();
 733 Local<ObjectTemplate> otmpl = ftmpl->InstanceTemplate();
 734 Local<Context> ctx =  NanNewContextHandle(NULL, otmpl);
 735 ```
 736
 737 <a href="#api_nan_get_current_context">
 738 ### Local<Context> NanGetCurrentContext()
 739
 740 Gets the current context.
 741
 742 ```c++
 743 Local<Context> ctx = NanGetCurrentContext();
 744 ```
 745
 746 <a name="api_nan_dispose_persistent"></a>
 747 ### void NanDisposePersistent(Persistent&lt;T&gt; &)
 748
 749 Use `NanDisposePersistent` to dispose a `Persistent` handle.
 750
 751 ```c++
 752 NanDisposePersistent(persistentHandle);
 753 ```
 754
 755 <a name="api_nan_assign_persistent"></a>
 756 ### NanAssignPersistent(type, handle, object)
 757
 758 Use `NanAssignPersistent` to assign a non-`Persistent` handle to a `Persistent` one. You can no longer just declare a `Persistent` handle and assign directly to it later, you have to `Reset` it in Node 0.11, so this makes it easier.
 759
 760 In general it is now better to place anything you want to protect from V8's garbage collector as properties of a generic `Object` and then assign that to a `Persistent`. This works in older versions of Node also if you use `NanAssignPersistent`:
 761
 762 ```c++
 763 Persistent<Object> persistentHandle;
 764
 765 ...
 766
 767 Local<Object> obj = NanNew<Object>();
 768 obj->Set(NanSymbol("key"), keyHandle); // where keyHandle might be a Local<String>
 769 NanAssignPersistent(Object, persistentHandle, obj)
 770 ```
 771
 772 <a name="api_nan_make_weak_persistent"></a>
 773 ### NanMakeWeakPersistent(Handle&lt;T&gt; handle, P* parameter, _NanWeakCallbackInfo&lt;T, P&gt;::Callback callback)
 774
 775 Creates a weak persistent handle with the supplied parameter and `NAN_WEAK_CALLBACK`. The callback has to be fully specialized to work on all versions of Node.
 776
 777 ```c++
 778 NAN_WEAK_CALLBACK(weakCallback) {
 779
 780 ...
 781
 782 }
 783
 784 Local<Function> func;
 785
 786 ...
 787
 788 int *parameter = new int(0);
 789 NanMakeWeakPersistent(func, parameter, &weakCallback<Function, int>);
 790 ```
 791
 792 <a name="api_nan_set_template"></a>
 793 ### NanSetTemplate(templ, name, value)
 794
 795 Use to add properties on object and function templates.
 796
 797 <a name="api_nan_make_callback"></a>
 798 ### NanMakeCallback(target, func, argc, argv)
 799
 800 Use instead of `node::MakeCallback` to call javascript functions. This is the only proper way of calling functions.
 801
 802 <a name="api_nan_compile_script"></a>
 803 ### NanCompileScript(Handle<String> s [, const ScriptOrigin&amp; origin])
 804
 805 Use to create new scripts bound to the current context.
 806
 807 <a name="api_nan_run_script"></a>
 808 ### NanRunScript(script)
 809
 810 Use to run both bound and unbound scripts.
 811
 812 <a name="api_nan_adjust_external_memory"></a>
 813 ### NanAdjustExternalMemory(int change_in_bytes)
 814
 815 Simply does `AdjustAmountOfExternalAllocatedMemory`
 816
 817 <a name="api_nan_add_gc_epilogue_callback"></a>
 818 ### NanAddGCEpilogueCallback(GCEpilogueCallback callback, GCType gc_type_filter=kGCTypeAll)
 819
 820 Simply does `AddGCEpilogueCallback`
 821
 822 <a name="api_nan_add_gc_prologue_callback"></a>
 823 ### NanAddGCPrologueCallback(GCPrologueCallback callback, GCType gc_type_filter=kGCTypeAll)
 824
 825 Simply does `AddGCPrologueCallback`
 826
 827 <a name="api_nan_remove_gc_epilogue_callback"></a>
 828 ### NanRemoveGCEpilogueCallback(GCEpilogueCallback callback)
 829
 830 Simply does `RemoveGCEpilogueCallback`
 831
 832 <a name="api_nan_add_gc_prologue_callback"></a>
 833 ### NanRemoveGCPrologueCallback(GCPrologueCallback callback)
 834
 835 Simply does `RemoveGCPrologueCallback`
 836
 837 <a name="api_nan_get_heap_statistics"></a>
 838 ### NanGetHeapStatistics(HeapStatistics *heap_statistics)
 839
 840 Simply does `GetHeapStatistics`
 841
 842 <a name="api_nan_callback"></a>
 843 ### NanCallback
 844
 845 Because of the difficulties imposed by the changes to `Persistent` handles in V8 in Node 0.11, creating `Persistent` versions of your `Handle<Function>` is annoyingly tricky. `NanCallback` makes it easier by taking your handle, making it persistent until the `NanCallback` is deleted and even providing a handy `Call()` method to fetch and execute the callback `Function`.
 846
 847 ```c++
 848 Local<Function> callbackHandle = args[0].As<Function>();
 849 NanCallback *callback = new NanCallback(callbackHandle);
 850 // pass `callback` around and it's safe from GC until you:
 851 delete callback;
 852 ```
 853
 854 You can execute the callback like so:
 855
 856 ```c++
 857 // no arguments:
 858 callback->Call(0, NULL);
 859
 860 // an error argument:
 861 Handle<Value> argv[] = {
 862   NanError(NanNew<String>("fail!"))
 863 };
 864 callback->Call(1, argv);
 865
 866 // a success argument:
 867 Handle<Value> argv[] = {
 868   NanNull(),
 869   NanNew<String>("w00t!")
 870 };
 871 callback->Call(2, argv);
 872 ```
 873
 874 `NanCallback` also has a `Local<Function> GetCallback()` method that you can use
 875 to fetch a local handle to the underlying callback function, as well  as a
 876 `void SetFunction(Handle<Function>)` for setting the callback on the
 877 `NanCallback`.  Additionally a generic constructor is available for using
 878 `NanCallback` without performing heap allocations.
 879
 880 <a name="api_nan_async_worker"></a>
 881 ### NanAsyncWorker
 882
 883 `NanAsyncWorker` is an abstract class that you can subclass to have much of the annoying async queuing and handling taken care of for you. It can even store arbitrary V8 objects for you and have them persist while the async work is in progress.
 884
 885 See a rough outline of the implementation:
 886
 887 ```c++
 888 class NanAsyncWorker {
 889 public:
 890   NanAsyncWorker (NanCallback *callback);
 891
 892   // Clean up persistent handles and delete the *callback
 893   virtual ~NanAsyncWorker ();
 894
 895   // Check the `char *errmsg` property and call HandleOKCallback()
 896   // or HandleErrorCallback depending on whether it has been set or not
 897   virtual void WorkComplete ();
 898
 899   // You must implement this to do some async work. If there is an
 900   // error then allocate `errmsg` to a message and the callback will
 901   // be passed that string in an Error object
 902   virtual void Execute ();
 903
 904   // Save a V8 object in a Persistent handle to protect it from GC
 905   void SavePersistent(const char *key, Local<Object> &obj);
 906
 907   // Fetch a stored V8 object (don't call from within `Execute()`)
 908   Local<Object> GetFromPersistent(const char *key);
 909
 910 protected:
 911   // Set this if there is an error, otherwise it's NULL
 912   const char *errmsg;
 913
 914   // Default implementation calls the callback function with no arguments.
 915   // Override this to return meaningful data
 916   virtual void HandleOKCallback ();
 917
 918   // Default implementation calls the callback function with an Error object
 919   // wrapping the `errmsg` string
 920   virtual void HandleErrorCallback ();
 921 };
 922 ```
 923
 924 <a name="api_nan_async_queue_worker"></a>
 925 ### NanAsyncQueueWorker(NanAsyncWorker *)
 926
 927 `NanAsyncQueueWorker` will run a `NanAsyncWorker` asynchronously via libuv. Both the *execute* and *after_work* steps are taken care of for you&mdash;most of the logic for this is embedded in `NanAsyncWorker`.
 928
 929 ### Contributors
 930
 931 NAN is only possible due to the excellent work of the following contributors:
 932
 933 <table><tbody>
 934 <tr><th align="left">Rod Vagg</th><td><a href="https://github.com/rvagg">GitHub/rvagg</a></td><td><a href="http://twitter.com/rvagg">Twitter/@rvagg</a></td></tr>
 935 <tr><th align="left">Benjamin Byholm</th><td><a href="https://github.com/kkoopa/">GitHub/kkoopa</a></td></tr>
 936 <tr><th align="left">Trevor Norris</th><td><a href="https://github.com/trevnorris">GitHub/trevnorris</a></td><td><a href="http://twitter.com/trevnorris">Twitter/@trevnorris</a></td></tr>
 937 <tr><th align="left">Nathan Rajlich</th><td><a href="https://github.com/TooTallNate">GitHub/TooTallNate</a></td><td><a href="http://twitter.com/TooTallNate">Twitter/@TooTallNate</a></td></tr>
 938 <tr><th align="left">Brett Lawson</th><td><a href="https://github.com/brett19">GitHub/brett19</a></td><td><a href="http://twitter.com/brett19x">Twitter/@brett19x</a></td></tr>
 939 <tr><th align="left">Ben Noordhuis</th><td><a href="https://github.com/bnoordhuis">GitHub/bnoordhuis</a></td><td><a href="http://twitter.com/bnoordhuis">Twitter/@bnoordhuis</a></td></tr>
 940 </tbody></table>
 941
 942 Licence &amp; copyright
 943 -----------------------
 944
 945 Copyright (c) 2014 NAN contributors (listed above).
 946
 947 Native Abstractions for Node.js is licensed under an MIT +no-false-attribs license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.