QuantumLibrary
Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator > Class Template Reference

Implementation of a key-based task sequencing with quantum. More...

#include <quantum_sequencer.h>

Public Types

using Configuration = SequencerConfiguration< SequenceKey, Hash, KeyEqual, Allocator >
 Configuration class for Sequencer. More...
 

Public Member Functions

 Sequencer (Dispatcher &dispatcher, const Configuration &configuration=Configuration())
 Constructor. More...
 
template<class FUNC , class ... ARGS>
void post (const SequenceKey &sequenceKey, FUNC &&func, ARGS &&... args)
 Post a coroutine to run asynchronously. More...
 
template<class FUNC , class ... ARGS>
void post (void *opaque, int queueId, bool isHighPriority, const SequenceKey &sequenceKey, FUNC &&func, ARGS &&... args)
 Post a coroutine to run asynchronously on a specific queue (thread). More...
 
template<class FUNC , class ... ARGS>
void post (const std::vector< SequenceKey > &sequenceKeys, FUNC &&func, ARGS &&... args)
 Post a coroutine to run asynchronously. More...
 
template<class FUNC , class ... ARGS>
void post (void *opaque, int queueId, bool isHighPriority, const std::vector< SequenceKey > &sequenceKeys, FUNC &&func, ARGS &&... args)
 Post a coroutine to run asynchronously on a specific queue (thread). More...
 
template<class FUNC , class ... ARGS>
void postAll (FUNC &&func, ARGS &&... args)
 Post a coroutine to run asynchronously. More...
 
template<class FUNC , class ... ARGS>
void postAll (void *opaque, int queueId, bool isHighPriority, FUNC &&func, ARGS &&... args)
 Post a coroutine to run asynchronously on a specific queue (thread). More...
 
size_t trimSequenceKeys ()
 Trims the sequence keys not used by the sequencer anymore. More...
 
size_t getSequenceKeyCount ()
 Gets the number of tracked sequence keys. More...
 
SequenceKeyStatistics getStatistics (const SequenceKey &sequenceKey)
 Gets the sequencer statistics for a specific sequence key. More...
 
SequenceKeyStatistics getStatistics ()
 Gets the sequencer statistics for the 'universal key', a.k.a. posted via postAll() method. More...
 
SequenceKeyStatistics getTaskStatistics ()
 Gets the sequencer statistics for all jobs. More...
 

Detailed Description

template<class SequenceKey, class Hash = std::hash<SequenceKey>, class KeyEqual = std::equal_to<SequenceKey>, class Allocator = std::allocator<std::pair<const SequenceKey, SequenceKeyData>>>
class Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >

Implementation of a key-based task sequencing with quantum.

Template Parameters
SequenceKeyType of the key based that sequenced tasks are associated with
HashHash-function used for storing instances of SequenceKey in hash maps
KeyEqualThe equal-function used for storing instances of SequenceKey in hash maps
AllocatorThe allocator used for storing instances of SequenceKey in hash maps

Member Typedef Documentation

◆ Configuration

template<class SequenceKey , class Hash = std::hash<SequenceKey>, class KeyEqual = std::equal_to<SequenceKey>, class Allocator = std::allocator<std::pair<const SequenceKey, SequenceKeyData>>>
using Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::Configuration = SequencerConfiguration<SequenceKey, Hash, KeyEqual, Allocator>

Constructor & Destructor Documentation

◆ Sequencer()

template<class SequenceKey , class Hash = std::hash<SequenceKey>, class KeyEqual = std::equal_to<SequenceKey>, class Allocator = std::allocator<std::pair<const SequenceKey, SequenceKeyData>>>
Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::Sequencer ( Dispatcher dispatcher,
const Configuration configuration = Configuration() 
)

Constructor.

Parameters
[in]dispatcherDispatcher for all task dispatching
[in]configurationthe configuration object

Member Function Documentation

◆ getSequenceKeyCount()

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
size_t Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::getSequenceKeyCount ( )

Gets the number of tracked sequence keys.

Returns
sequence key count
Note
This function blocks until the statistics computation job posted to the dispatcher is finished.

◆ getStatistics() [1/2]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
SequenceKeyStatistics Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::getStatistics ( const SequenceKey &  sequenceKey)

Gets the sequencer statistics for a specific sequence key.

Parameters
sequenceKeythe key
Returns
the statistics objects for the specified key
Note
This function blocks until the statistics computation job posted to the dispatcher is finished.

◆ getStatistics() [2/2]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
SequenceKeyStatistics Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::getStatistics ( )

Gets the sequencer statistics for the 'universal key', a.k.a. posted via postAll() method.

Returns
the statistics objects
Note
This function blocks until the statistics computation job posted to the dispatcher is finished.

◆ getTaskStatistics()

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
SequenceKeyStatistics Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::getTaskStatistics ( )

Gets the sequencer statistics for all jobs.

Returns
the statistics objects
Note
The difference with the previous two statistics methods is that it aggregates stats on a per-task basis, not on per-key basis.

◆ post() [1/4]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
template<class FUNC , class ... ARGS>
void Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::post ( const SequenceKey &  sequenceKey,
FUNC &&  func,
ARGS &&...  args 
)

Post a coroutine to run asynchronously.

This method will post the coroutine on any thread available and will run when the previous coroutine associated with the same 'sequenceKey' completes. If there are none, it will run immediately. (

See also
Dispatcher::post for more details).
Template Parameters
FUNCCallable object type which will be wrapped in a coroutine
ARGSArgument types passed to FUNC (
See also
Dispatcher::post for more details).
Parameters
[in]sequenceKeySequenceKey object that the posted task is associated with
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and returns immediately.
Remarks
For lowering the latencies of processing tasks posted here, it is suggested that the configured Any-coroutine-queue-range (
See also
Configuration::setCoroQueueIdRangeForAny) does not contain the control queue id (
SequencerConfiguration::setControlQueueId).

◆ post() [2/4]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
template<class FUNC , class ... ARGS>
void Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::post ( void *  opaque,
int  queueId,
bool  isHighPriority,
const SequenceKey &  sequenceKey,
FUNC &&  func,
ARGS &&...  args 
)

Post a coroutine to run asynchronously on a specific queue (thread).

This method will post the coroutine on any thread available and will run when the previous coroutine associated with the same 'sequenceKey' completes. If there are none, it will run immediately. (

See also
Dispatcher::post for more details).
Template Parameters
FUNCCallable object type which will be wrapped in a coroutine
ARGSArgument types passed to FUNC (
See also
Dispatcher::post for more details).
Parameters
[in]queueIdId of the queue where this coroutine should run. Note that the user can specify IQueue::QueueId::Any as a value, which is equivalent to running the simpler version of post() above. Valid range is [0, numCoroutineThreads) or IQueue::QueueId::Any.
[in]isHighPriorityIf set to true, the sequencer coroutine will be scheduled right after the currently executing coroutine on 'queueId'.
[in]opaquepointer to opaque data that is passed to the exception handler (if provided) if an unhandled exception is thrown in func
[in]sequenceKeySequenceKey object that the posted task is associated with
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and returns immediately.
Remarks
For lowering the latencies of processing tasks posted here, queueId is suggested to be different from the control queue id (
See also
SequencerConfiguration::setControlQueueId). Hence, if IQueue::QueueId::Any is intended to be used as queueId here, then it is suggested that the configured Any-coroutine-queue-range (
Configuration::setCoroQueueIdRangeForAny) does not contain the control queue id.

◆ post() [3/4]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
template<class FUNC , class ... ARGS>
void Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::post ( const std::vector< SequenceKey > &  sequenceKeys,
FUNC &&  func,
ARGS &&...  args 
)

Post a coroutine to run asynchronously.

This method will post the coroutine on any thread available and will run when the previous coroutine(s) associated with all the 'sequenceKeys' complete. If there are none, then it will run immediately. (

See also
Dispatcher::post for more details).
Template Parameters
FUNCCallable object type which will be wrapped in a coroutine
ARGSArgument types passed to FUNC (
See also
Dispatcher::post for more details).
Parameters
[in]sequenceKeysA collection of sequenceKey objects that the posted task is associated with
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and returns immediately.
Remarks
For lowering the latencies of processing tasks posted here, it is suggested that the configured Any-coroutine-queue-range (
See also
Configuration::setCoroQueueIdRangeForAny) does not contain the control queue id (
SequencerConfiguration::setControlQueueId).

◆ post() [4/4]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
template<class FUNC , class ... ARGS>
void Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::post ( void *  opaque,
int  queueId,
bool  isHighPriority,
const std::vector< SequenceKey > &  sequenceKeys,
FUNC &&  func,
ARGS &&...  args 
)

Post a coroutine to run asynchronously on a specific queue (thread).

This method will post the coroutine on any thread available and will run when the previous coroutine(s) associated with all the 'sequenceKeys' complete. If there are none, then it will run immediately. (

See also
Dispatcher::post for more details).
Template Parameters
FUNCCallable object type which will be wrapped in a coroutine.
ARGSArgument types passed to FUNC (
See also
Dispatcher::post for more details).
Parameters
[in]queueIdId of the queue where this coroutine should run. Note that the user can specify IQueue::QueueId::Any as a value, which is equivalent to running the simpler version of post() above. Valid range is [0, numCoroutineThreads) or IQueue::QueueId::Any.
[in]isHighPriorityIf set to true, the sequencer coroutine will be scheduled right after the currently executing coroutine on 'queueId'.
[in]opaquepointer to opaque data that is passed to the exception handler (if provided) if an unhandled exception is thrown in func
[in]sequenceKeysA collection of sequenceKey objects that the posted task is associated with
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and returns immediately.
Remarks
For lowering the latencies of processing tasks posted here, queueId is suggested to be different from the control queue id (
See also
SequencerConfiguration::setControlQueueId). Hence, if IQueue::QueueId::Any is intended to be used as queueId here, then it is suggested that the configured Any-coroutine-queue-range (
Configuration::setCoroQueueIdRangeForAny) does not contain the control queue id.

◆ postAll() [1/2]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
template<class FUNC , class ... ARGS>
void Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::postAll ( FUNC &&  func,
ARGS &&...  args 
)

Post a coroutine to run asynchronously.

This method will post the coroutine on any thread available. The posted task is assumed to be associated with the entire universe of sequenceKeys already running or pending, which means that it will wait until all tasks complete. This task can be considered as having a 'universal' key.

Template Parameters
FUNCCallable object type which will be wrapped in a coroutine
ARGSArgument types passed to FUNC (
See also
Dispatcher::post for more details).
Parameters
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and returns immediately.
Remarks
For lowering the latencies of processing tasks posted here, it is suggested that the configured Any-coroutine-queue-range (
See also
Configuration::setCoroQueueIdRangeForAny) does not contain the control queue id (
SequencerConfiguration::setControlQueueId).

◆ postAll() [2/2]

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
template<class FUNC , class ... ARGS>
void Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::postAll ( void *  opaque,
int  queueId,
bool  isHighPriority,
FUNC &&  func,
ARGS &&...  args 
)

Post a coroutine to run asynchronously on a specific queue (thread).

This method will post the coroutine on any thread available. The posted task is assumed to be associated with the entire universe of sequenceKeys already running or pending, which means that it will wait until all tasks complete. This task can be considered as having a 'universal' key.

Template Parameters
FUNCCallable object type which will be wrapped in a coroutine.
ARGSArgument types passed to FUNC (
See also
Dispatcher::post for more details).
Parameters
[in]queueIdId of the queue where this coroutine should run. Note that the user can specify IQueue::QueueId::Any as a value, which is equivalent to running the simpler version of post() above. Valid range is [0, numCoroutineThreads) or IQueue::QueueId::Any.
[in]isHighPriorityIf set to true, the sequencer coroutine will be scheduled right after the currently executing coroutine on 'queueId'.
[in]opaquepointer to opaque data that is passed to the exception handler (if provided) if an unhandled exception is thrown in func
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and returns immediately.
Remarks
For lowering the latencies of processing tasks posted here, queueId is suggested to be different from the control queue id (
See also
SequencerConfiguration::setControlQueueId). Hence, if IQueue::QueueId::Any is intended to be used as queueId here, then it is suggested that the configured Any-coroutine-queue-range (
Configuration::setCoroQueueIdRangeForAny) does not contain the control queue id.

◆ trimSequenceKeys()

template<class SequenceKey , class Hash , class KeyEqual , class Allocator >
size_t Bloomberg::quantum::Sequencer< SequenceKey, Hash, KeyEqual, Allocator >::trimSequenceKeys ( )

Trims the sequence keys not used by the sequencer anymore.

It's recommended to call this function periodically to clean up state sequence keys.

Remarks
This call clears all the statistics for trimmed keys.
Returns
The number of sequenceKeys after the trimming.
Note
This function blocks until the trimming job posted to the dispatcher is finished