‐ A simple interface that requires minimal extra code by the user. To use this interface efficiently the user‐provided functions must be copyable to folly::Function without dynamic allocation. If this is impossible or inconvenient, the user is encouraged to use the custom interface described below. ‐ A custom interface that supports custom combining and custom request structure, either for the sake of smart combining or for efficiently supporting operations that are not be copyable to folly::Function without dynamic allocation. ‐ Both synchronous and asynchronous operations. ‐ Request records with and without thread‐caching. ‐ Combining with and without a dedicated combiner thread.

Synopsis

Declared in <folly/synchronization/FlatCombining.h>

template<
    typename T,
    typename Mutex = std::mutex,
    template<typename> typename Atom = atomic,
    typename Req = bool>
class FlatCombining;

Description

This implementation differs from the algorithm in the SPAA 2010 paper:

  • It does not require thread caching of request records

  • It supports a dedicated combiner

  • It supports asynchronous operations

The generic FC class template supports generic data structures and utilities with arbitrary operations. The template supports static polymorphism for the combining function to enable custom smart combining.

A simple example of using the FC template: class ConcurrentFoo : public FlatCombining<ConcurrentFoo> { Foo foo_; // sequential data structure public: T bar(V& v) { // thread‐safe execution of foo_.bar(v) T result; // Note: fn must be copyable to folly::Function without dynamic // allocation. Otherwise, it is recommended to use the custom // interface and manage the function arguments and results // explicitly in a custom request structure. auto fn = [&]{ result = foo_.bar(v); }; this‐>requestFC(fn); return result; } };

See test/FlatCombiningExamples.h for more examples. See the comments for requestFC() below for a list of simple and custom variants of that function.

Types

Name

Description

Rec

Combining request record.

Type Aliases

Name

Description

Pool

Memory pool that owns and recycles combining request records.

Member Functions

Name

Description

FlatCombining [constructor]

Constructors

~FlatCombining [destructor]

Destructor: If there is a dedicated combiner, the destructor flags it to shutdown. Otherwise, the destructor waits for all pending asynchronous requests to be completed.

operator=

Assignment operators

acquireExclusive

Give the caller exclusive access.

allocRec

Allocate a record.

drainAll

Wait for all pending operations to complete. Useful primarily when there are asynchronous operations without a dedicated combiner.

freeRec

Free a record.

getNumCombined

Returns the number of combined operations so far.

getNumPasses

Returns the number of combining passes so far.

getNumSessions

Returns the number of combining sessions so far.

getNumUncombined

Returns the number of uncombined operations so far.

holdLock

holdLock overloads

releaseExclusive

Release exclusive access. The caller must have exclusive access.

requestFC

requestFC overloads

requestNoFC

Execute an operation without combining.

tryExclusive

Try to give the caller exclusive access.

Protected Member Functions

Name

Description

awaitDone

Waits for the given record's request to be done.

awaitDoneTryLock

Waits for the request to be done and occasionally tries to acquire the lock and to do combining. Used only in the absence of a dedicated combiner.

awaitPending

Blocks until the pending signal is raised.

clearPending

Clears the pending signal.

combinedOp

Executes a combined custom request; must be overridden by the derived class when the custom interface is used.

combiningPass

Performs one pass over the pending records, processing valid requests and disconnecting idle ones.

combiningSession

Runs one combining session over the pending records.

dedicatedCombining

Loop run by the dedicated combiner thread until shutdown.

getRecsHead

Returns the head index of the pending record list.

isPending

Reports whether the pending signal is raised.

nextIndex

Returns the index of the record following the given one.

processReq

Processes a single request record, running its function and completing it.

pushRec

Pushes a record index onto the head of the pending list.

requestOp

Core request path shared by all requestFC() overloads.

setPending

Raises the pending signal.

shutdown

Requests shutdown of the dedicated combiner thread.

tryCombining

Performs combining sessions while requests are pending, when there is no dedicated combiner.

Protected Data Members

Name

Description

NULL_INDEX

Sentinel index representing the absence of a record.

combined_

Running count of combined operations.

combiner_

The dedicated combiner thread, if any.

dedicated_

Whether a dedicated combiner thread is used.

kDefaultMaxOps

Default hint for the maximum operations per combining session.

kDefaultNumRecs

Default number of combining records.

kIdleThreshold

Number of idle passes after which the combiner may sleep.

m_

The mutex guarding exclusive access to the data structure.

maxOps_

The hint for the maximum operations per combining session.

numRecs_

The number of combining records in the pool.

passes_

Running count of combining passes.

pending_

Signals the dedicated combiner that requests are pending.

recsPool_

The pool that owns the combining records.

recs_

The head index of the list of pending records.

sessions_

Running count of combining sessions.

shutdown_

Set to request shutdown of the dedicated combiner.

uncombined_

Running count of uncombined operations.

Derived Classes

Name

Description

FlatCombiningPriorityQueue

Thread‐safe priority queue based on flat combining. If the constructor parameter maxSize is greater than 0 (default = 0), then the queue is bounded. This template provides blocking, non‐blocking, and timed variants of each of push(), pop(), and peek() operations. The empty() and size() functions are inherently non‐blocking.

Created with MrDocs