namespace folly {
/// DynamicBoundedQueue supports:
-
/// - Dynamic memory usage that grows and shrink in proportion to the
/// number of elements in the queue.
/// - Adjustable capacity that helps throttle pathological cases of
/// costly blocking.
/// - See DynamicBoundedQueueTest.cpp for some benchmark results.
///
-/// Template prameters:
+/// Template parameters:
/// - T: element type
/// - SingleProducer: true if there can be only one producer at a
/// time.
/// Tries to add an element to the end of the queue if
/// capacity allows it. Returns true if successful. Otherwise
/// Returns false.
-/// bool try_enqueue_until(const T&, time_point&);
-/// bool try_enqueue_until(T&&, time_point&);
+/// bool try_enqueue_until(const T&, time_point& deadline);
+/// bool try_enqueue_until(T&&, time_point& deadline);
/// Tries to add an element to the end of the queue if
-/// capacity allows it until the specified timepoint. Returns
+/// capacity allows it until the specified deadline. Returns
/// true if successful, otherwise false.
/// bool try_enqueue_for(const T&, duration&);
/// bool try_enqueue_for(T&&, duration&);
/// Tries to add an element to the end of the queue if
-/// capacity allows it until the specified timepoint. Returns
-/// true if successful, otherwise false.
+/// capacity allows until the expiration of the specified
+/// duration. Returns true if successful, otherwise false.
///
/// Consumer functions:
/// void dequeue(T&);
/// bool try_dequeue(T&);
/// Tries to extracts an element from the front of the queue
/// if available. Returns true if successful, otherwise false.
-/// bool try_dequeue_until(T&, time_point&);
+/// bool try_dequeue_until(T&, time_point& deadline);
/// Tries to extracts an element from the front of the queue
-/// if available until the specified time_point. Returns true
+/// if available until the specified daedline. Returns true
/// if successful. Otherwise Returns false.
/// bool try_dequeue_for(T&, duration&);
/// Tries to extracts an element from the front of the queue
/// - SingleConsumer: true if there can be only one consumer at a
/// time.
/// - MayBlock: true if consumers may block, false if they only
-/// spins. A performance tuning parameter.
+/// spin. A performance tuning parameter.
/// - LgSegmentSize (default 8): Log base 2 of number of elements per
/// segment. A performance tuning parameter. See below.
/// - LgAlign (default 7): Log base 2 of alignment directive; can be
/// Extracts an element from the front of the queue. Waits
/// until an element is available if needed.
/// bool try_dequeue(T&);
-/// Tries to extracts an element from the front of the queue
+/// Tries to extract an element from the front of the queue
/// if available. Returns true if successful, false otherwise.
/// bool try_dequeue_until(T&, time_point& deadline);
-/// Tries to extracts an element from the front of the queue
+/// Tries to extract an element from the front of the queue
/// if available until the specified deadline. Returns true
/// if successful, false otherwise.
/// bool try_dequeue_for(T&, duration&);
-/// Tries to extracts an element from the front of the queue
-/// if available for for the specified duration. Returns true
-/// if successful, false otherwise.
+/// Tries to extract an element from the front of the queue if
+/// available for until the expiration of the specified
+/// duration. Returns true if successful, false otherwise.
///
/// Secondary functions:
/// size_t size();
/// exactly once.
/// - Each entry is composed of a futex and a single element.
/// - The queue contains two 64-bit ticket variables. The producer
-/// ticket counts the number of producer tickets isued so far, and
+/// ticket counts the number of producer tickets issued so far, and
/// the same for the consumer ticket. Each ticket number corresponds
/// to a specific entry in a specific segment.
/// - The queue maintains two pointers, head and tail. Head points to
/// one or two more segment than fits its contents.
/// - Removed segments are not reclaimed until there are no threads,
/// producers or consumers, have references to them or their
-/// predessors. That is, a lagging thread may delay the reclamation
+/// predecessors. That is, a lagging thread may delay the reclamation
/// of a chain of removed segments.
/// - The template parameter LgAlign can be used to reduce memory usage
/// at the cost of increased chance of false sharing.
///
/// Performance considerations:
/// - All operations take constant time, excluding the costs of
-/// allocation, reclamation, interence from other threads, and
+/// allocation, reclamation, interference from other threads, and
/// waiting for actions by other threads.
/// - In general, using the single producer and or single consumer
-/// variants yields better performance than the MP and MC
+/// variants yield better performance than the MP and MC
/// alternatives.
/// - SPSC without blocking is the fastest configuration. It doesn't
/// include any read-modify-write atomic operations, full fences, or
/// - MC adds a fetch_add or compare_exchange to the critical path of
/// each consumer operation.
/// - The possibility of consumers blocking, even if they never do,
-/// adds a compare_exchange to the crtical path of each producer
+/// adds a compare_exchange to the critical path of each producer
/// operation.
/// - MPMC, SPMC, MPSC require the use of a deferred reclamation
/// mechanism to guarantee that segments removed from the linked
/// - Another consideration is that the queue is guaranteed to have
/// enough space for a number of consumers equal to 2^LgSegmentSize
/// for local blocking. Excess waiting consumers spin.
-/// - It is recommended to measure perforamnce with different variants
+/// - It is recommended to measure performance with different variants
/// when applicable, e.g., UMPMC vs UMPSC. Depending on the use
/// case, sometimes the variant with the higher sequential overhead
/// may yield better results due to, for example, more favorable
-/// producer-consumer balance or favorable timining for avoiding
+/// producer-consumer balance or favorable timing for avoiding
/// costly blocking.
template <
projects / folly.git / commitdiff