Document try_enqueue implicit producer index limit (#418) by PavelGuzenfeld · Pull Request #446 · cameron314/concurrentqueue

PavelGuzenfeld · 2026-03-17T18:48:59Z

Summary

Added documentation to ConcurrentQueueDefaultTraits::IMPLICIT_INITIAL_INDEX_SIZE explaining the relationship between BLOCK_SIZE, IMPLICIT_INITIAL_INDEX_SIZE, and the maximum elements per implicit producer when using try_enqueue
Added clarifying note on the try_enqueue method that pre-allocating blocks via the constructor does not increase the block index size
Added implicit_producer_index_limit unit test demonstrating the limit and both workarounds (use enqueue() or increase IMPLICIT_INITIAL_INDEX_SIZE)

Test plan

Unit test implicit_producer_index_limit passes (8 iterations, all green)
Full test suite builds with gcc:14

Fixes #418

PavelGuzenfeld · 2026-03-18T21:33:12Z

Hi @cameron314, just a friendly ping on this PR. Would you have a chance to take a look when convenient? Happy to address any feedback. Thank you!

cameron314

Thanks for opening this PR. This is definitely a gotcha that's bitten quite a few people over the years and improving the documentation around it is definitely worth doing.

cameron314 · 2026-03-28T16:34:16Z

tests/unittests/unittests.cpp

+		}
+
+		{
+			// Fix #1: enqueue() (which can allocate) works past the limit


To me, this comment reads as if this is testing a fix in the code, whereas it's actually demonstrating a workaround to the API behaving as designed.

Suggested change

// Fix #1: enqueue() (which can allocate) works past the limit

// Workaround #1: enqueue() (which can allocate) can grow the index

cameron314 · 2026-03-28T16:36:30Z

tests/unittests/unittests.cpp

+		}
+
+		{
+			// Fix #2: larger IMPLICIT_INITIAL_INDEX_SIZE allows more try_enqueue calls


Suggested change

// Fix #2: larger IMPLICIT_INITIAL_INDEX_SIZE allows more try_enqueue calls

// Workaround #2: larger IMPLICIT_INITIAL_INDEX_SIZE allows more try_enqueue calls

cameron314 · 2026-03-28T16:55:09Z

concurrentqueue.h

+	// Note: This controls the maximum number of elements that can be enqueued by a
+	// single implicit producer when using try_enqueue (which does not allocate).
+	// The limit is BLOCK_SIZE * IMPLICIT_INITIAL_INDEX_SIZE elements; beyond that,
+	// the block index needs to grow, which requires allocation, causing try_enqueue
+	// to fail. Increase this value (or use enqueue(), which can allocate) if you need
+	// more capacity per implicit producer. See also issue #418.


This is one limiting factor, but not the only one (BLOCK_SIZE plays a role too, and the number of blocks preallocated, and it's possible to mix try_enqueue and enqueue).

I'm also not sure I like stating BLOCK_SIZE * IMPLICIT_INITIAL_INDEX_SIZE elements, since blocks are not necessarily full: if all blocks are filled up to this many elements, then one element is dequeued, a new element still can't be enqueued until the entire first block is emptied.

Also not sure I like referencing github issues in non-test code.

How about:

Suggested change

// Note: This controls the maximum number of elements that can be enqueued by a

// single implicit producer when using try_enqueue (which does not allocate).

// The limit is BLOCK_SIZE * IMPLICIT_INITIAL_INDEX_SIZE elements; beyond that,

// the block index needs to grow, which requires allocation, causing try_enqueue

// to fail. Increase this value (or use enqueue(), which can allocate) if you need

// more capacity per implicit producer. See also issue #418.

// Note: This impacts the maximum number of elements that can be enqueued by a

// single implicit producer when using try_enqueue/try_enqeue_bulk exclusively (which

// cannot allocate), since it limits the number of blocks that the producer can hold to

// store elements. When pre-allocating blocks for use with try-enqueueing, configure

// this initial size to the desired maximum number of blocks per implicit producer.

// Alternately, use the regular enqueue methods, which can grow the index as needed.

cameron314 · 2026-03-28T16:58:10Z

blockingconcurrentqueue.h

 	// memory barrier).
 	explicit BlockingConcurrentQueue(size_t capacity = 6 * BLOCK_SIZE)
-		: inner(capacity), sema(create<LightweightSemaphore, ssize_t, int>(0, (int)Traits::MAX_SEMA_SPINS), &BlockingConcurrentQueue::template destroy<LightweightSemaphore>)
+		: inner(capacity), sema(create<LightweightSemaphore, ssize_t, int>(0, static_cast<int>(Traits::MAX_SEMA_SPINS)), &BlockingConcurrentQueue::template destroy<LightweightSemaphore>)


These casts were also introduced in a separate PR and now conflict with master.

cameron314 · 2026-03-28T17:03:43Z

concurrentqueue.h

+	// Note: For implicit producers (no token), the maximum number of elements that
+	// can be held is BLOCK_SIZE * IMPLICIT_INITIAL_INDEX_SIZE before the block
+	// index must grow (which requires allocation and causes try_enqueue to fail).
+	// Pre-allocating blocks via the constructor does not increase the index size.
+	// Increase IMPLICIT_INITIAL_INDEX_SIZE in your traits, or use enqueue() instead.


This method does not accept a token, so it is implicit by definition.

Given the thorough note in the trait docs, I think it's fine to leave a shorter comment here referencing the traits.

Suggested change

// Note: For implicit producers (no token), the maximum number of elements that

// can be held is BLOCK_SIZE * IMPLICIT_INITIAL_INDEX_SIZE before the block

// index must grow (which requires allocation and causes try_enqueue to fail).

// Pre-allocating blocks via the constructor does not increase the index size.

// Increase IMPLICIT_INITIAL_INDEX_SIZE in your traits, or use enqueue() instead.

// Note: If using only try_enqueue/try_enqueue_bulk with pre-allocated blocks, configure

// Traits::IMPLICIT_INITIAL_INDEX_SIZE appropriately to ensure the index has sufficient

// capacity for the number of blocks each producer may need.

There are also other implicit try-enqueueing methods to which this note would equally apply. It should appear consistently on each.

…ameron314#418) try_enqueue() fails around BLOCK_SIZE * IMPLICIT_INITIAL_INDEX_SIZE elements per implicit producer because the block index (not the blocks) must grow, which requires allocation that try_enqueue refuses to do. Pre-allocating blocks via the constructor does not help. Added documentation comments near IMPLICIT_INITIAL_INDEX_SIZE in the default traits and near the try_enqueue method explaining the limit and workarounds. Added implicit_producer_index_limit unit test demonstrating the issue and verifying both workarounds (enqueue() and larger IMPLICIT_INITIAL_INDEX_SIZE).

- Reword traits doc comment per maintainer's suggestion (no formula, no issue ref) - Shorten try_enqueue note and add it consistently to all implicit try-enqueue methods - Rename "Fix" to "Workaround" in test comments (behavior is by design)

PavelGuzenfeld

Applied all suggested changes and rebased on master.

PavelGuzenfeld force-pushed the fix/try-enqueue-implicit-index-docs-418 branch from 911509e to 1a7c45f Compare March 17, 2026 18:50

cameron314 requested changes Mar 28, 2026

View reviewed changes

PavelGuzenfeld added 2 commits March 29, 2026 00:22

Address review feedback from cameron314

217f4af

- Reword traits doc comment per maintainer's suggestion (no formula, no issue ref) - Shorten try_enqueue note and add it consistently to all implicit try-enqueue methods - Rename "Fix" to "Workaround" in test comments (behavior is by design)

PavelGuzenfeld force-pushed the fix/try-enqueue-implicit-index-docs-418 branch from b2f1b31 to 217f4af Compare March 28, 2026 21:22

PavelGuzenfeld commented Mar 28, 2026

View reviewed changes

PavelGuzenfeld requested a review from cameron314 March 28, 2026 21:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document try_enqueue implicit producer index limit (#418)#446

Document try_enqueue implicit producer index limit (#418)#446
PavelGuzenfeld wants to merge 2 commits intocameron314:masterfrom
PavelGuzenfeld:fix/try-enqueue-implicit-index-docs-418

PavelGuzenfeld commented Mar 17, 2026

Uh oh!

PavelGuzenfeld commented Mar 18, 2026

Uh oh!

cameron314 left a comment

Uh oh!

cameron314 Mar 28, 2026

Uh oh!

cameron314 Mar 28, 2026

Uh oh!

cameron314 Mar 28, 2026 •

edited

Loading

Uh oh!

cameron314 Mar 28, 2026

Uh oh!

cameron314 Mar 28, 2026

Uh oh!

PavelGuzenfeld left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	// Fix #1: enqueue() (which can allocate) works past the limit
	// Workaround #1: enqueue() (which can allocate) can grow the index

	// Fix #2: larger IMPLICIT_INITIAL_INDEX_SIZE allows more try_enqueue calls
	// Workaround #2: larger IMPLICIT_INITIAL_INDEX_SIZE allows more try_enqueue calls

Conversation

PavelGuzenfeld commented Mar 17, 2026

Summary

Test plan

Uh oh!

PavelGuzenfeld commented Mar 18, 2026

Uh oh!

cameron314 left a comment

Choose a reason for hiding this comment

Uh oh!

cameron314 Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

cameron314 Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

cameron314 Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cameron314 Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

cameron314 Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

PavelGuzenfeld left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cameron314 Mar 28, 2026 •

edited

Loading