From: Maged Michael Date: Sat, 16 Dec 2017 02:18:07 +0000 (-0800) Subject: Fix comments in UnboundedQueue and DynamicBoundedQueue X-Git-Tag: v2017.12.18.00~5 X-Git-Url: http://plrg.eecs.uci.edu/git/?p=folly.git;a=commitdiff_plain;h=a123a11e30026dd9883f16fa3ad1baa2d9ecfeec Fix comments in UnboundedQueue and DynamicBoundedQueue Summary: Fix typos and wording in comments. Reviewed By: yfeldblum Differential Revision: D6584559 fbshipit-source-id: b4b72f6c25c9f9e6fb3f2fbee69eea4a39b5c004 --- diff --git a/folly/concurrency/DynamicBoundedQueue.h b/folly/concurrency/DynamicBoundedQueue.h index 8e7e839f..e6634b8d 100644 --- a/folly/concurrency/DynamicBoundedQueue.h +++ b/folly/concurrency/DynamicBoundedQueue.h @@ -27,7 +27,6 @@ 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 @@ -87,7 +86,7 @@ namespace folly { /// 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. @@ -122,16 +121,16 @@ namespace folly { /// 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&); @@ -140,9 +139,9 @@ namespace folly { /// 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 diff --git a/folly/concurrency/UnboundedQueue.h b/folly/concurrency/UnboundedQueue.h index 2f2571cc..7459c263 100644 --- a/folly/concurrency/UnboundedQueue.h +++ b/folly/concurrency/UnboundedQueue.h @@ -43,7 +43,7 @@ namespace folly { /// - 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 @@ -79,16 +79,16 @@ namespace folly { /// 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(); @@ -126,7 +126,7 @@ namespace folly { /// 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 @@ -150,17 +150,17 @@ namespace folly { /// 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 @@ -169,7 +169,7 @@ namespace folly { /// - 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 @@ -184,11 +184,11 @@ namespace folly { /// - 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 <