Skip to content

Commit

Permalink
doc: add Buffer.from(string) to functions that use buffer pool
Browse files Browse the repository at this point in the history
Buffer.from(string) is one of the functions that may use the
pre-allocated buffer. It's mentioned in the description of
Buffer.from(array), but not in Buffer.from(string), or in the two other
places where functions that behave this way are listed, so this commit
adds those references.

PR-URL: nodejs#52801
Reviewed-By: Vinícius Lourenço Claro Cardoso <[email protected]>
Reviewed-By: James M Snell <[email protected]>
  • Loading branch information
Whitecx authored and EliphazBouye committed Jun 20, 2024
1 parent 1e0195f commit 82a4ce8
Showing 1 changed file with 13 additions and 10 deletions.
23 changes: 13 additions & 10 deletions doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -808,7 +808,7 @@ 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()`][], [`Buffer.from(array)`][],
and [`Buffer.concat()`][] only when `size` is less than
[`Buffer.from(string)`][], and [`Buffer.concat()`][] only when `size` is less than
`Buffer.poolSize >>> 1` (floor of [`Buffer.poolSize`][] divided by two).

Use of this pre-allocated internal memory pool is a key difference between
Expand Down Expand Up @@ -846,11 +846,11 @@ _may contain sensitive data_. Use [`buf.fill(0)`][`buf.fill()`] to initialize
such `Buffer` instances with zeroes.

When using [`Buffer.allocUnsafe()`][] to allocate new `Buffer` instances,
allocations under 4 KiB are sliced from a single pre-allocated `Buffer`. This
allows applications to avoid the garbage collection overhead of creating many
individually allocated `Buffer` instances. This approach improves both
performance and memory usage by eliminating the need to track and clean up as
many individual `ArrayBuffer` objects.
allocations less than `Buffer.poolSize >>> 1` (4KiB when default poolSize is used) are sliced
from a single pre-allocated `Buffer`. This allows applications to avoid the
garbage collection overhead of creating many individually allocated `Buffer`
instances. This approach improves both performance and memory usage by
eliminating the need to track and clean up as many individual `ArrayBuffer` objects.

However, in the case where a developer may need to retain a small chunk of
memory from a pool for an indeterminate amount of time, it may be appropriate
Expand Down Expand Up @@ -1390,6 +1390,9 @@ console.log(buf1.toString('latin1'));
A `TypeError` will be thrown if `string` is not a string or another type
appropriate for `Buffer.from()` variants.

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

### Static method: `Buffer.isBuffer(obj)`

<!-- YAML
Expand Down Expand Up @@ -5444,10 +5447,10 @@ 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()`][] 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
`Buffer` instances returned by [`Buffer.allocUnsafe()`][], [`Buffer.from(string)`][],
[`Buffer.concat()`][] 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
Expand Down

0 comments on commit 82a4ce8

Please sign in to comment.