96 lines
3.7 KiB
C++
96 lines
3.7 KiB
C++
//
|
|
// Copyright 2017 The Abseil Authors.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
//
|
|
// -----------------------------------------------------------------------------
|
|
// blocking_counter.h
|
|
// -----------------------------------------------------------------------------
|
|
|
|
#ifndef ABSL_SYNCHRONIZATION_BLOCKING_COUNTER_H_
|
|
#define ABSL_SYNCHRONIZATION_BLOCKING_COUNTER_H_
|
|
|
|
#include "absl/base/thread_annotations.h"
|
|
#include "absl/synchronization/mutex.h"
|
|
|
|
namespace absl {
|
|
|
|
// BlockingCounter
|
|
//
|
|
// This class allows a thread to block for a pre-specified number of actions.
|
|
// `BlockingCounter` maintains a single non-negative abstract integer "count"
|
|
// with an initial value `initial_count`. A thread can then call `Wait()` on
|
|
// this blocking counter to block until the specified number of events occur;
|
|
// worker threads then call 'DecrementCount()` on the counter upon completion of
|
|
// their work. Once the counter's internal "count" reaches zero, the blocked
|
|
// thread unblocks.
|
|
//
|
|
// A `BlockingCounter` requires the following:
|
|
// - its `initial_count` is non-negative.
|
|
// - the number of calls to `DecrementCount()` on it is at most
|
|
// `initial_count`.
|
|
// - `Wait()` is called at most once on it.
|
|
//
|
|
// Given the above requirements, a `BlockingCounter` provides the following
|
|
// guarantees:
|
|
// - Once its internal "count" reaches zero, no legal action on the object
|
|
// can further change the value of "count".
|
|
// - When `Wait()` returns, it is legal to destroy the `BlockingCounter`.
|
|
// - When `Wait()` returns, the number of calls to `DecrementCount()` on
|
|
// this blocking counter exactly equals `initial_count`.
|
|
//
|
|
// Example:
|
|
// BlockingCounter bcount(N); // there are N items of work
|
|
// ... Allow worker threads to start.
|
|
// ... On completing each work item, workers do:
|
|
// ... bcount.DecrementCount(); // an item of work has been completed
|
|
//
|
|
// bcount.Wait(); // wait for all work to be complete
|
|
//
|
|
class BlockingCounter {
|
|
public:
|
|
explicit BlockingCounter(int initial_count)
|
|
: count_(initial_count), num_waiting_(0) {}
|
|
|
|
BlockingCounter(const BlockingCounter&) = delete;
|
|
BlockingCounter& operator=(const BlockingCounter&) = delete;
|
|
|
|
// BlockingCounter::DecrementCount()
|
|
//
|
|
// Decrements the counter's "count" by one, and return "count == 0". This
|
|
// function requires that "count != 0" when it is called.
|
|
//
|
|
// Memory ordering: For any threads X and Y, any action taken by X
|
|
// before it calls `DecrementCount()` is visible to thread Y after
|
|
// Y's call to `DecrementCount()`, provided Y's call returns `true`.
|
|
bool DecrementCount();
|
|
|
|
// BlockingCounter::Wait()
|
|
//
|
|
// Blocks until the counter reaches zero. This function may be called at most
|
|
// once. On return, `DecrementCount()` will have been called "initial_count"
|
|
// times and the blocking counter may be destroyed.
|
|
//
|
|
// Memory ordering: For any threads X and Y, any action taken by X
|
|
// before X calls `DecrementCount()` is visible to Y after Y returns
|
|
// from `Wait()`.
|
|
void Wait();
|
|
|
|
private:
|
|
Mutex lock_;
|
|
int count_ GUARDED_BY(lock_);
|
|
int num_waiting_ GUARDED_BY(lock_);
|
|
};
|
|
|
|
} // namespace absl
|
|
#endif // ABSL_SYNCHRONIZATION_BLOCKING_COUNTER_H_
|