Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

docs: moar

  • Loading branch information...
commit 107c7cfcff9298f4452218ec061d679b5c0b3f84 1 parent 2425c69
@TooTallNate authored
Showing with 43 additions and 15 deletions.
  1. +43 −15 lib/ref.js
View
58 lib/ref.js
@@ -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,7 +666,8 @@ 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
*/
@@ -665,9 +675,20 @@ exports._attach = function _attach (buf, obj) {
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,9 +698,9 @@ 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
*/
@@ -687,8 +708,16 @@ exports.writeObject = function writeObject (buf, offset, obj) {
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) {
Please sign in to comment.
Something went wrong with that request. Please try again.