Skip to content

Commit 5b03579

Browse files
committed
Docs: more details about concurrency, parallelism, threads
1 parent 58c2af3 commit 5b03579

File tree

3 files changed

+37
-9
lines changed

3 files changed

+37
-9
lines changed

docs/api-utility.md

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -95,18 +95,31 @@ Returns **[Object][1]**
9595
## concurrency
9696

9797
Gets or, when a concurrency is provided, sets
98-
the number of threads *libvips'* should create to process each image.
98+
the maximum number of threads *libvips* should use to process *each image*.
99+
These are from a thread pool managed by glib,
100+
which helps avoid the overhead of creating new threads.
101+
102+
This method always returns the current concurrency.
99103

100104
The default value is the number of CPU cores,
101105
except when using glibc-based Linux without jemalloc,
102106
where the default is `1` to help reduce memory fragmentation.
103107

104108
A value of `0` will reset this to the number of CPU cores.
105109

106-
The maximum number of images that can be processed in parallel
107-
is limited by libuv's `UV_THREADPOOL_SIZE` environment variable.
110+
Some image format libraries spawn additional threads,
111+
e.g. libaom manages its own 4 threads when encoding AVIF images,
112+
and these are independent of the value set here.
108113

109-
This method always returns the current concurrency.
114+
The maximum number of images that sharp can process in parallel
115+
is controlled by libuv's `UV_THREADPOOL_SIZE` environment variable,
116+
which defaults to 4.
117+
118+
[https://nodejs.org/api/cli.html#uv_threadpool_sizesize][12]
119+
120+
For example, by default, a machine with 8 CPU cores will process
121+
4 images in parallel and use up to 8 threads per image,
122+
so there will be up to 32 concurrent threads.
110123

111124
### Parameters
112125

@@ -199,3 +212,5 @@ Returns **[boolean][10]**
199212
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
200213

201214
[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
215+
216+
[12]: https://nodejs.org/api/cli.html#uv_threadpool_sizesize

0 commit comments

Comments
 (0)