Skip to content

Commit 88ab4bd

Browse files
committed
Clarify importance of default hash sizes in traits when using try_enqueue exclusively (relates to #292)
1 parent 65d6970 commit 88ab4bd

1 file changed

Lines changed: 9 additions & 0 deletions

File tree

README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,15 @@ If these formulas seem rather inconvenient, you can use the constructor overload
303303
number of elements (`N`) and the maximum number of explicit and implicit producers directly, and let it do the
304304
computation for you.
305305

306+
In addition to blocks, there are other internal data structures that require allocating memory if they need to resize (grow).
307+
If using `try_enqueue` exclusively, the initial sizes may be exceeded, causing subsequent `try_enqueue` operations to fail.
308+
Specifically, the `INITIAL_IMPLICIT_PRODUCER_HASH_SIZE` trait limits the number of implicit producers that can be active at once
309+
before the internal hash needs resizing. Along the same lines, the `IMPLICIT_INITIAL_INDEX_SIZE` trait limits the number of
310+
unconsumed elements that an implicit producer can insert before its internal hash needs resizing. Similarly, the
311+
`EXPLICIT_INITIAL_INDEX_SIZE` trait limits the number of unconsumed elements that an explicit producer can insert before its
312+
internal hash needs resizing. In order to avoid hitting these limits when using `try_enqueue`, it is crucial to adjust the
313+
initial sizes in the traits appropriately, in addition to sizing the number of blocks properly as outlined above.
314+
306315
Finally, it's important to note that because the queue is only eventually consistent and takes advantage of
307316
weak memory ordering for speed, there's always a possibility that under contention `try_enqueue` will fail
308317
even if the queue is correctly pre-sized for the desired number of elements. (e.g. A given thread may think that

0 commit comments

Comments
 (0)