{ "source": "doc/api/smalloc.markdown", "modules": [ { "textRaw": "Smalloc", "name": "smalloc", "stability": 1, "stabilityText": "Experimental", "classes": [ { "textRaw": "Class: smalloc", "type": "class", "name": "smalloc", "desc": "
Buffers are backed by a simple allocator that only handles the assignation of\nexternal raw memory. Smalloc exposes that functionality.\n\n
\n", "methods": [ { "textRaw": "smalloc.alloc(length[, receiver][, type])", "type": "method", "name": "alloc", "signatures": [ { "params": [ { "textRaw": "`length` {Number} `<= smalloc.kMaxLength` ", "name": "length", "type": "Number", "desc": "`<= smalloc.kMaxLength`" }, { "textRaw": "`receiver` {Object} Default: `new Object` ", "name": "receiver", "type": "Object", "desc": "Default: `new Object`", "optional": true }, { "textRaw": "`type` {Enum} Default: `Uint8` ", "name": "type", "type": "Enum", "desc": "Default: `Uint8`", "optional": true } ] }, { "params": [ { "name": "length" }, { "name": "receiver", "optional": true }, { "name": "type", "optional": true } ] } ], "desc": "Returns receiver
with allocated external array data. If no receiver
is\npassed then a new Object will be created and returned.\n\n
This can be used to create your own Buffer-like classes. No other properties are\nset, so the user will need to keep track of other necessary information (e.g.\nlength
of the allocation).\n\n
function SimpleData(n) {\n this.length = n;\n smalloc.alloc(this.length, this);\n}\n\nSimpleData.prototype = { /* ... */ };
\nIt only checks if the receiver
is an Object, and also not an Array. Because of\nthis it is possible to allocate external array data to more than a plain Object.\n\n
function allocMe() { }\nsmalloc.alloc(3, allocMe);\n\n// { [Function allocMe] '0': 0, '1': 0, '2': 0 }
\nv8 does not support allocating external array data to an Array, and if passed\nwill throw.\n\n
\nIt's possible to specify the type of external array data you would like. All\npossible options are listed in smalloc.Types
. Example usage:\n\n
var doubleArr = smalloc.alloc(3, smalloc.Types.Double);\n\nfor (var i = 0; i < 3; i++)\n doubleArr = i / 10;\n\n// { '0': 0, '1': 0.1, '2': 0.2 }
\nIt is not possible to freeze, seal and prevent extensions of objects with\nexternal data using Object.freeze
, Object.seal
and\nObject.preventExtensions
respectively.\n\n
Free memory that has been allocated to an object via smalloc.alloc
.\n\n
var a = {};\nsmalloc.alloc(3, a);\n\n// { '0': 0, '1': 0, '2': 0 }\n\nsmalloc.dispose(a);\n\n// {}
\nThis is useful to reduce strain on the garbage collector, but developers must be\ncareful. Cryptic errors may arise in applications that are difficult to trace.\n\n
\nvar a = smalloc.alloc(4);\nvar b = smalloc.alloc(4);\n\n// perform this somewhere along the line\nsmalloc.dispose(b);\n\n// now trying to copy some data out\nsmalloc.copyOnto(b, 2, a, 0, 2);\n\n// now results in:\n// RangeError: copy_length > source_length
\nAfter dispose()
is called object still behaves as one with external data, for\nexample smalloc.hasExternalData()
returns true
.\ndispose()
does not support Buffers, and will throw if passed.\n\n
Returns true
if the obj
has externally allocated memory.\n\n
Copy memory from one external array allocation to another. No arguments are\noptional, and any violation will throw.\n\n
\nvar a = smalloc.alloc(4);\nvar b = smalloc.alloc(4);\n\nfor (var i = 0; i < 4; i++) {\n a[i] = i;\n b[i] = i * 2;\n}\n\n// { '0': 0, '1': 1, '2': 2, '3': 3 }\n// { '0': 0, '1': 2, '2': 4, '3': 6 }\n\nsmalloc.copyOnto(b, 2, a, 0, 2);\n\n// { '0': 4, '1': 6, '2': 2, '3': 3 }
\ncopyOnto
automatically detects the length of the allocation internally, so no\nneed to set any additional properties for this to work.\n\n
Size of maximum allocation. This is also applicable to Buffer creation.\n\n
\n" }, { "textRaw": "smalloc.Types", "name": "Types", "desc": "Enum of possible external array types. Contains:\n\n
\nInt8
Uint8
Int16
Uint16
Int32
Uint32
Float
Double
Uint8Clamped