Skip to content

Commit

Permalink
doc: document buffer.from returns internal pool buffer
Browse files Browse the repository at this point in the history
Fixes: #22139

Co-authored-by: Mritunjay Goutam <[email protected]>

PR-URL: #32703
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: James M Snell <[email protected]>
  • Loading branch information
HarshithaKP authored and BethGriggs committed Apr 14, 2020
1 parent 63f0dd1 commit a7c75f9
Showing 1 changed file with 12 additions and 7 deletions.
19 changes: 12 additions & 7 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -379,9 +379,10 @@ A `TypeError` will be thrown if `size` is not a number.

The `Buffer` module pre-allocates an internal `Buffer` instance of
size [`Buffer.poolSize`][] that is used as a pool for the fast allocation of new
`Buffer` instances created using [`Buffer.allocUnsafe()`][] and the deprecated
`new Buffer(size)` constructor only when `size` is less than or equal to
`Buffer.poolSize >> 1` (floor of [`Buffer.poolSize`][] divided by two).
`Buffer` instances created using [`Buffer.allocUnsafe()`][],
[`Buffer.from(array)`][], and the deprecated `new Buffer(size)` constructor only
when `size` is less than or equal to `Buffer.poolSize >> 1` (floor of
[`Buffer.poolSize`][] divided by two).

Use of this pre-allocated internal memory pool is a key difference between
calling `Buffer.alloc(size, fill)` vs. `Buffer.allocUnsafe(size).fill(fill)`.
Expand Down Expand Up @@ -571,6 +572,9 @@ const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
A `TypeError` will be thrown if `array` is not an `Array` or other type
appropriate for `Buffer.from()` variants.

`Buffer.from(array)` and [`Buffer.from(string)`][] may also use the internal
`Buffer` pool like [`Buffer.allocUnsafe()`][] does.

### Class Method: `Buffer.from(arrayBuffer[, byteOffset[, length]])`
<!-- YAML
added: v5.10.0
Expand Down Expand Up @@ -2733,10 +2737,11 @@ to one of these new APIs.*
uninitialized, the allocated segment of memory might contain old data that is
potentially sensitive.

`Buffer` instances returned by [`Buffer.allocUnsafe()`][] *may* be allocated off
a shared internal memory pool if `size` is less than or equal to half
[`Buffer.poolSize`][]. Instances returned by [`Buffer.allocUnsafeSlow()`][]
*never* use the shared internal memory pool.
`Buffer` instances returned by [`Buffer.allocUnsafe()`][] and
[`Buffer.from(array)`][] *may* be allocated off a shared internal memory pool
if `size` is less than or equal to half [`Buffer.poolSize`][]. Instances
returned by [`Buffer.allocUnsafeSlow()`][] *never* use the shared internal
memory pool.

### The `--zero-fill-buffers` command line option
<!-- YAML
Expand Down

0 comments on commit a7c75f9

Please sign in to comment.