Permalink
Browse files

docs: moar

  • Loading branch information...
TooTallNate committed Jul 5, 2012
1 parent 2425c69 commit 107c7cfcff9298f4452218ec061d679b5c0b3f84
Showing with 43 additions and 15 deletions.
  1. +43 −15 lib/ref.js
View
@@ -630,6 +630,15 @@ exports.ref = function ref (buffer) {
* When _buffer_'s indirection is at __1__, then it checks for `buffer.type`
* which should be an Object with its own `get()` function.
*
* ```
* var buf = ref.alloc('int', 6);
*
* var val = ref.deref(buf);
* console.log(val);
* 6
* ```
*
*
* @param {Buffer} buffer A Buffer instance to dereference.
* @return {?} The returned value after dereferencing _buffer_.
*/
@@ -640,11 +649,11 @@ exports.deref = function deref (buffer) {
}
/**
* Meant for retaining references to Objects/Buffers in JS-land
* from calls to `_writeObject()` and `_writePointer()`. C-land doesn't retain the
* source Buffer in `writePointer()`, and `writeObject()` uses a weak reference
* when writing the Object, so attaching afterwards in necessary. See below...
* Attaches _object_ to _buffer_ such that it prevents _object_ from being garbage
* collected until _buffer_ does.
*
* @param {Buffer} buffer A Buffer instance to attach _object_ to.
* @param {Object|Buffer} object An Object or Buffer to prevent from being garbage collected until _buffer_ does.
* @api private
*/
@@ -657,17 +666,29 @@ exports._attach = function _attach (buf, obj) {
/**
* Same as `ref.writeObject()`, except that this version does not _attach_ the
* Object to the Buffer, which is potentially unsafe.
* Object to the Buffer, which is potentially unsafe if the garbage collector
* runs.
*
* @api private
*/
exports._writeObject = exports.writeObject
/**
* The private `_writeObject()` function does the actual writing of the given
* Object to the given Buffer instance. This version does not _attach_ the Object
* to the Buffer, which is potentially unsafe.
* Writes a pointer to _object_ into _buffer_ at the specified _offset.
*
* This function "attaches" _object_ to _buffer_ to prevent it from being garbage
* collected.
*
* ```
* var buf = ref.alloc('Object');
* ref.writeObject(buf, 0, { foo: 'bar' });
*
* ```
*
* @param {Buffer} buffer A Buffer instance to write _object_ to.
* @param {Number} offset The offset on the Buffer to start writing at.
* @param {Object} object A Buffer instance to write _object_ to.
*/
exports.writeObject = function writeObject (buf, offset, obj) {
@@ -677,18 +698,26 @@ exports.writeObject = function writeObject (buf, offset, obj) {
}
/**
* The private `writePointer()` function does the actual writing of the given
* pointer Buffer to the target Buffer instance. This version does not _attach_
* the pointer Buffer to the target Buffer, which is potentially unsafe.
* Same as `ref.writePointer()`, except that this version does not attach
* _pointer_ to _buffer_, which is potentially unsafe if the garbage collector
* runs.
*
* @api private
*/
exports._writePointer = exports.writePointer
/**
* Overwrite the native "writePointer" function so that it keeps a ref to the
* passed in Buffer in JS-land by adding it to the Bufer's _refs array.
* Writes the memory address of _pointer_ to _buffer_ at the specified _offset_.
*
* This function "attaches" _object_ to _buffer_ to prevent it from being garbage
* collected.
*
* ```
* var someBuffer = new Buffer('whatever');
* var buf = ref.alloc('pointer');
* ref.writePointer(buf, 0, someBuffer);
* ```
*/
exports.writePointer = function writePointer (buf, offset, ptr) {
@@ -739,12 +768,11 @@ exports._reinterpretUntilZeros = exports.reinterpretUntilZeros
* This is useful for finding the end of NUL-termintated array or C string. For
* example, the `readCString()` function _could_ be implemented like:
*
* ``` js
* ```
* function readCString (buf) {
* return ref.reinterpretUntilZeros(buf, 1).toString('utf8')
* }
* ```
*
*/
exports.reinterpretUntilZeros = function reinterpretUntilZeros (buffer, size) {

0 comments on commit 107c7cf

Please sign in to comment.