Skip to content

Commit

Permalink
buffer: use smalloc as backing data store
Browse files Browse the repository at this point in the history
Memory allocations are now done through smalloc. The Buffer cc class has
been removed completely, but for backwards compatibility have left the
namespace as Buffer.

The .parent attribute is only set if the Buffer is a slice of an
allocation. Which is then set to the alloc object (not a Buffer).

The .offset attribute is now a ReadOnly set to 0, for backwards
compatibility. I'd like to remove it in the future (pre v1.0).

A few alterations have been made to how arguments are either coerced or
thrown. All primitives will now be coerced to their respective values,
and (most) all out of range index requests will throw.

The indexes that are coerced were left for backwards compatibility. For
example: Buffer slice operates more like Array slice, and coerces
instead of throwing out of range indexes. This may change in the future.

The reason for wanting to throw for out of range indexes is because
giving js access to raw memory has high potential risk. To mitigate that
it's easier to make sure the developer is always quickly alerted to the
fact that their code is attempting to access beyond memory bounds.

Because SlowBuffer will be deprecated, and simply returns a new Buffer
instance, all tests on SlowBuffer have been removed.

Heapdumps will now show usage under "smalloc" instead of "Buffer".

ParseArrayIndex was added to node_internals to support proper uint
argument checking/coercion for external array data indexes.

SlabAllocator had to be updated since handle_ no longer exists.
  • Loading branch information
trevnorris committed Jun 18, 2013
1 parent 252cdfa commit 3a2f273
Show file tree
Hide file tree
Showing 20 changed files with 695 additions and 1,286 deletions.
133 changes: 65 additions & 68 deletions doc/api/buffer.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,69 @@ Allocates a new buffer containing the given `str`.
Returns true if the `encoding` is a valid encoding argument, or false
otherwise.

### Class Method: Buffer.isBuffer(obj)

* `obj` Object
* Return: Boolean

Tests if `obj` is a `Buffer`.

### Class Method: Buffer.byteLength(string, [encoding])

* `string` String
* `encoding` String, Optional, Default: 'utf8'
* Return: Number

Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
This is not the same as `String.prototype.length` since that returns the
number of *characters* in a string.

Example:

str = '\u00bd + \u00bc = \u00be';

console.log(str + ": " + str.length + " characters, " +
Buffer.byteLength(str, 'utf8') + " bytes");

// ½ + ¼ = ¾: 9 characters, 12 bytes

### Class Method: Buffer.concat(list, [totalLength])

* `list` {Array} List of Buffer objects to concat
* `totalLength` {Number} Total length of the buffers when concatenated

Returns a buffer which is the result of concatenating all the buffers in
the list together.

If the list has no items, or if the totalLength is 0, then it returns a
zero-length buffer.

If the list has exactly one item, then the first item of the list is
returned.

If the list has more than one item, then a new Buffer is created.

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.

### buf.length

* Number

The size of the buffer in bytes. Note that this is not necessarily the size
of the contents. `length` refers to the amount of memory allocated for the
buffer object. It does not change when the contents of the buffer are changed.

buf = new Buffer(1234);

console.log(buf.length);
buf.write("some string", 0, "ascii");
console.log(buf.length);

// 1234
// 1234

### buf.write(string, [offset], [length], [encoding])

* `string` String - data to be written to buffer
Expand Down Expand Up @@ -155,69 +218,6 @@ Example: copy an ASCII string into a buffer, one byte at a time:

// node.js

### Class Method: Buffer.isBuffer(obj)

* `obj` Object
* Return: Boolean

Tests if `obj` is a `Buffer`.

### Class Method: Buffer.byteLength(string, [encoding])

* `string` String
* `encoding` String, Optional, Default: 'utf8'
* Return: Number

Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
This is not the same as `String.prototype.length` since that returns the
number of *characters* in a string.

Example:

str = '\u00bd + \u00bc = \u00be';

console.log(str + ": " + str.length + " characters, " +
Buffer.byteLength(str, 'utf8') + " bytes");

// ½ + ¼ = ¾: 9 characters, 12 bytes

### Class Method: Buffer.concat(list, [totalLength])

* `list` {Array} List of Buffer objects to concat
* `totalLength` {Number} Total length of the buffers when concatenated

Returns a buffer which is the result of concatenating all the buffers in
the list together.

If the list has no items, or if the totalLength is 0, then it returns a
zero-length buffer.

If the list has exactly one item, then the first item of the list is
returned.

If the list has more than one item, then a new Buffer is created.

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.

### buf.length

* Number

The size of the buffer in bytes. Note that this is not necessarily the size
of the contents. `length` refers to the amount of memory allocated for the
buffer object. It does not change when the contents of the buffer are changed.

buf = new Buffer(1234);

console.log(buf.length);
buf.write("some string", 0, "ascii");
console.log(buf.length);

// 1234
// 1234

### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])

* `targetBuffer` Buffer object - Buffer to copy into
Expand Down Expand Up @@ -694,11 +694,8 @@ Note that this is a property on the buffer module returned by

## Class: SlowBuffer

This class is primarily for internal use. JavaScript programs should
use Buffer instead of using SlowBuffer.
Deprecated. SlowBuffer now returns an instance of Buffer.

In order to avoid the overhead of allocating many C++ Buffer objects for
small blocks of memory in the lifetime of a server, Node allocates memory
in 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it
will be backed by a parent SlowBuffer object. If it is larger than this,
then Node will allocate a SlowBuffer slab for it directly.
in 8Kb (8192 byte) chunks. This is now handled by Smalloc.
Loading

0 comments on commit 3a2f273

Please sign in to comment.