buffer: expose class methods alloc and dispose

Expose the ability for users to allocate and manually dispose data on
any object. These are user-safe versions of internal smalloc functions.

diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown
index d880911..3ddd413 100644 (file)
--- a/doc/api/buffer.markdown
+++ b/doc/api/buffer.markdown
@@ -126,6 +126,46 @@ If totalLength is not provided, it is read from the buffers in the list.
 However, this adds an additional loop to the function, so it is faster
 to provide the length explicitly.
 
+### Class Method: Buffer.alloc(length, [receiver])
+
+* `length` Number
+* `receiver` Object, Optional, Default: `new Object`
+
+
+**(EXPERIMENTAL)** Returns object with allocated external array data.
+
+Buffers are backed by a simple allocator that only handles the assignation of
+external raw memory. This exposes that functionality.
+
+No pooling is performed for these allocations. So there's no form of memory
+leak.
+
+This can be used to create your own Buffer-like classes.
+
+    function SimpleData(n) {
+      this.length = n;
+      Buffer.alloc(this.length, this);
+    }
+
+    SimpleData.prototype = { /* ... */ };
+
+### Class Method: Buffer.dispose(obj)
+
+* `obj` Object
+
+
+**(EXPERIMENTAL)** Free memory that has been allocated to an object via
+`Buffer.alloc`.
+
+    var a = {};
+    Buffer.alloc(3, a);
+
+    // { '0': 0, '1': 0, '2': 0 }
+
+    Buffer.dispose(a);
+
+    // {}
+
 ### buf.length
 
 * Number

diff --git a/lib/buffer.js b/lib/buffer.js
index e0ce4c5..a21fb79 100644 (file)
--- a/lib/buffer.js
+++ b/lib/buffer.js
@@ -176,6 +176,26 @@ Buffer.concat = function(list, length) {
 };
 
 
+Buffer.alloc = function(n, obj) {
+  n = ~~n;
+  if (n < 0) n = 0;
+
+  if (n > kMaxLength)
+    throw new RangeError('n > kMaxLength');
+  if (Array.isArray(obj))
+    throw new TypeError('Arrays are not supported');
+
+  return alloc(obj != null ? obj : {}, n);
+};
+
+
+Buffer.dispose = function(obj) {
+  if (obj instanceof Buffer)
+    throw new TypeError('obj cannot be a Buffer');
+  smalloc.dispose(obj);
+};
+
+
 // toString(encoding, start=0, end=buffer.length)
 Buffer.prototype.toString = function(encoding, start, end) {
   encoding = !!encoding ? (encoding + '').toLowerCase() : 'utf8';

diff --git a/test/simple/test-buffer.js b/test/simple/test-buffer.js
index b5a76d9..19fa4ea 100644 (file)
--- a/test/simple/test-buffer.js
+++ b/test/simple/test-buffer.js
@@ -923,3 +923,40 @@ assert.equal(Buffer.byteLength('aaaa==', 'base64'), 3);
 assert.throws(function() {
   Buffer('', 'buffer');
 }, TypeError);
+
+
+// test Buffer alloc
+
+// arrays are unsupported by v8
+assert.throws(function() {
+  Buffer.alloc(0, []);
+}, TypeError);
+
+// can't create too large an alloc
+assert.throws(function() {
+  Buffer.alloc(0x3fffffff + 1);
+}, RangeError);
+
+// make sure values are assigned
+var b = {};
+Buffer.alloc(256, b);
+for (var i = 0; i < 256; i++)
+  b[i] = i;
+for (var i = 0; i < 256; i++)
+  assert.equal(b[i], i);
+assert.equal(b[257], undefined);
+
+// several other types that shouldn't throw
+Buffer.alloc(1, function() { });
+Buffer.alloc(1, /abc/);
+Buffer.alloc(1, new Date());
+
+
+// make sure disposal works
+var b = {};
+Buffer.alloc(5, b);
+for (var i = 0; i < 5; i++)
+  b[i] = i;
+Buffer.dispose(b);
+for (var i = 0; i < 5; i++)
+  assert.equal(b[i], undefined);