Skip to content

doc: document buffer.from returns internal pool buffer #32703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

doc: document buffer.from returns internal pool buffer #32703

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9032369
doc: document `buffer.from` returns internal pool buffer
HarshithaKP Apr 7, 2020
b156733
fixup: address review comment
HarshithaKP Apr 7, 2020
1f5ccd8
fixup: address review comment
HarshithaKP Apr 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions doc/api/buffer.md
View file
Open in desktop
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 @@ -2726,10 +2730,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