diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown index d880911f0d..3ddd413208 100644 --- 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 e0ce4c545e..a21fb79f2e 100644 --- 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 b5a76d90f8..19fa4eacb0 100644 --- 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);