node/doc/api/smalloc.markdown

Smalloc

Stability: 1 - Experimental

smalloc.alloc(length[, receiver])

• length Number <= smalloc.kMaxLength
• receiver Object, Optional, Default: new Object

Returns receiver with allocated external array data. If no receiver is passed then a new Object will be created and returned.

Buffers are backed by a simple allocator that only handles the assignation of external raw memory. Smalloc exposes that functionality.

This can be used to create your own Buffer-like classes. No other properties are set, so the user will need to keep track of other necessary information (e.g. length of the allocation).

function SimpleData(n) {
  this.length = n;
  smalloc.alloc(this.length, this);
}

SimpleData.prototype = { /* ... */ };

It only checks if the receiver is an Object, and also not an Array. Because of this it is possible to allocate external array data to more than a plain Object.

function allocMe() { }
smalloc.alloc(3, allocMe);

// { [Function allocMe] '0': 0, '1': 0, '2': 0 }

v8 does not support allocating external array data to an Array, and if passed will throw.

smalloc.copyOnto(source, sourceStart, dest, destStart, copyLength);

• source Object with external array allocation
• sourceStart Position to begin copying from
• dest Object with external array allocation
• destStart Position to begin copying onto
• copyLength Length of copy

Copy memory from one external array allocation to another. No arguments are optional, and any violation will throw.

var a = smalloc.alloc(4);
var b = smalloc.alloc(4);

for (var i = 0; i < 4; i++) {
  a[i] = i;
  b[i] = i * 2;
}

// { '0': 0, '1': 1, '2': 2, '3': 3 }
// { '0': 0, '1': 2, '2': 4, '3': 6 }

smalloc.copyOnto(b, 2, a, 0, 2);

// { '0': 4, '1': 6, '2': 2, '3': 3 }

copyOnto automatically detects the length of the allocation internally, so no need to set any additional properties for this to work.

smalloc.dispose(obj)

• obj Object

Free memory that has been allocated to an object via smalloc.alloc.

var a = {};
smalloc.alloc(3, a);

// { '0': 0, '1': 0, '2': 0 }

smalloc.dispose(a);

// {}

This is useful to reduce strain on the garbage collector, but developers must be careful. Cryptic errors may arise in applications that are difficult to trace.

var a = smalloc.alloc(4);
var b = smalloc.alloc(4);

// perform this somewhere along the line
smalloc.dispose(b);

// now trying to copy some data out
smalloc.copyOnto(b, 2, a, 0, 2);

// now results in:
// Error: source has no external array data

dispose() does not support Buffers, and will throw if passed.

smalloc.kMaxLength

Size of maximum allocation. This is also applicable to Buffer creation.