QuantumLibrary
Bloomberg::quantum::IThreadContext< RET > Interface Template Referenceabstract

Exposes methods to manipulate the thread context. More...

#include <quantum_ithread_context.h>

Inheritance diagram for Bloomberg::quantum::IThreadContext< RET >:
Bloomberg::quantum::IThreadContextBase Bloomberg::quantum::IContextBase Bloomberg::quantum::Context< RET >

Public Types

using ContextTag = ThreadContextTag
 
using Ptr = std::shared_ptr< IThreadContext< RET > >
 
using Impl = Context< RET >
 
- Public Types inherited from Bloomberg::quantum::IThreadContextBase
using Ptr = std::shared_ptr< IThreadContextBase >
 
- Public Types inherited from Bloomberg::quantum::IContextBase
using Ptr = std::shared_ptr< IContextBase >
 

Public Member Functions

virtual void wait () const =0
 Waits for the future associated with this context to be ready. More...
 
virtual std::future_status waitFor (std::chrono::milliseconds timeMs) const =0
 Waits for the future associated with this context to be ready for a maximum of 'timeMs' milliseconds. More...
 
virtual void waitAt (int num) const =0
 Waits for the future in the 'num-th' continuation context to be ready. More...
 
virtual std::future_status waitForAt (int num, std::chrono::milliseconds timeMs) const =0
 Waits for the future in the 'num-th' continuation context to be ready for a maximum of 'timeMs' milliseconds. More...
 
virtual void waitAll () const =0
 Wait for all the futures in the continuation chain to be ready. More...
 
template<class V = RET>
NonBufferRetType< V > get ()
 Get the future value associated with this context. More...
 
template<class V = RET>
const NonBufferRetType< V > & getRef () const
 Get a reference the future value associated with this context. More...
 
template<class OTHER_RET >
NonBufferRetType< OTHER_RET > getAt (int num)
 Get the future value from the 'num-th' continuation context. More...
 
template<class OTHER_RET >
const NonBufferRetType< OTHER_RET > & getRefAt (int num) const
 Get a reference to the future value from the 'num-th' continuation context. More...
 
template<class V , class = NonBufferType<RET,V>>
int set (V &&value)
 Set the promised value associated with this context. More...
 
template<class V , class = BufferType<RET,V>>
void push (V &&value)
 Push a single value into the promise buffer. More...
 
template<class V = RET>
BufferRetType< V > pull (bool &isBufferClosed)
 Pull a single value from the future buffer. More...
 
template<class V = RET, class = BufferRetType<V>>
int closeBuffer ()
 Close a promise buffer. More...
 
int getNumCoroutineThreads () const
 Returns the number of underlying coroutine threads as specified in the dispatcher constructor. If -1 was passed than this number essentially indicates the number of cores. More...
 
int getNumIoThreads () const
 Returns the number of underlying IO threads as specified in the dispatcher constructor. More...
 
const std::pair< int, int > & getCoroQueueIdRangeForAny () const
 Gets the range [minQueueId, maxQueueId] of coroutine queueIds covered by IQueue::QueueId::Any by the Dispatcher. More...
 
template<class OTHER_RET = int, class FUNC , class ... ARGS>
IThreadContext< OTHER_RET >::Ptr then (FUNC &&func, ARGS &&... args)
 Posts a function to run asynchronously. More...
 
template<class OTHER_RET = int, class FUNC , class ... ARGS>
IThreadContext< OTHER_RET >::Ptr onError (FUNC &&func, ARGS &&... args)
 Posts a function to run asynchronously. This is the error handler for a continuation chain and acts as as a 'catch' clause. More...
 
template<class OTHER_RET = int, class FUNC , class ... ARGS>
IThreadContext< OTHER_RET >::Ptr finally (FUNC &&func, ARGS &&... args)
 Posts a function to run asynchronously. This function is always guaranteed to run. More...
 
Ptr end ()
 This is the last method in a continuation chain. More...
 
template<class OTHER_RET , class FUNC , class ... ARGS>
ThreadContextPtr< OTHER_RET > then (FUNC &&func, ARGS &&... args)
 
template<class OTHER_RET , class FUNC , class ... ARGS>
ThreadContextPtr< OTHER_RET > onError (FUNC &&func, ARGS &&... args)
 
template<class OTHER_RET , class FUNC , class ... ARGS>
ThreadContextPtr< OTHER_RET > finally (FUNC &&func, ARGS &&... args)
 
- Public Member Functions inherited from Bloomberg::quantum::IContextBase
virtual ~IContextBase ()=default
 Virtual destructor. More...
 
virtual bool valid () const =0
 Determines if the future object associated with this context has a valid shared state with the corresponding promise. More...
 
virtual bool validAt (int num) const =0
 Determines if the future object associated with the 'num'-th continuation context is still valid. More...
 
virtual int setException (std::exception_ptr ex)=0
 Set an exception in the promise associated with the current IThreadContext or ICoroContext. More...
 

Detailed Description

template<class RET>
interface Bloomberg::quantum::IThreadContext< RET >

Exposes methods to manipulate the thread context.

Template Parameters
RETThe type of value returned via the promise associated with this context.

Member Typedef Documentation

◆ ContextTag

template<class RET>
using Bloomberg::quantum::IThreadContext< RET >::ContextTag = ThreadContextTag

◆ Impl

template<class RET>
using Bloomberg::quantum::IThreadContext< RET >::Impl = Context<RET>

◆ Ptr

template<class RET>
using Bloomberg::quantum::IThreadContext< RET >::Ptr = std::shared_ptr<IThreadContext<RET> >

Member Function Documentation

◆ closeBuffer()

template<class RET >
template<class V , class >
int Bloomberg::quantum::IThreadContext< RET >::closeBuffer ( )

Close a promise buffer.

Template Parameters
BUFRepresents a class of type Buffer.
Note
Once closed no more Pushes can be made into the buffer. The corresponding future can still Pull values until the buffer is empty.
Returns
0 on success.

Implemented in Bloomberg::quantum::Context< RET >.

◆ end()

template<class RET >
IThreadContext< RET >::Ptr Bloomberg::quantum::IThreadContext< RET >::end ( )

This is the last method in a continuation chain.

This method effectively closes the continuation chain and posts the entire chain to be executed, respecting the 'queueId' and priority specified at the beginning of the chain (see postFirst()).

Returns
Pointer to this context.
Note
This method does not take any functions as parameter as it is strictly used for scheduling purposes.

Implemented in Bloomberg::quantum::Context< RET >.

◆ finally() [1/2]

template<class RET>
template<class OTHER_RET , class FUNC , class ... ARGS>
ThreadContextPtr<OTHER_RET> Bloomberg::quantum::IThreadContext< RET >::finally ( FUNC &&  func,
ARGS &&...  args 
)

◆ finally() [2/2]

template<class RET>
template<class OTHER_RET = int, class FUNC , class ... ARGS>
IThreadContext<OTHER_RET>::Ptr Bloomberg::quantum::IThreadContext< RET >::finally ( FUNC &&  func,
ARGS &&...  args 
)

Posts a function to run asynchronously. This function is always guaranteed to run.

This function is optional for the continuation chain and may be called at most once. If called, it must immediately precede the end() method. This method will run regardless if any preceding functions have an error or not. It can be used for cleanup purposes, closing handles, terminating services, etc.

Template Parameters
OTHER_RETType of future returned by this function.
FUNCCallable object type. Can be a standalone function, a method, an std::function, a functor generated via std::bind or a lambda. The signature of the callable object must strictly be 'int f(CoroContext<RET>::Ptr, ...)'.
ARGSArgument types passed to FUNC.
Parameters
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and returns immediately. After this function, the end() method must be called.

Implemented in Bloomberg::quantum::Context< RET >, and Bloomberg::quantum::Context< RET >.

◆ get()

template<class RET >
template<class V >
NonBufferRetType< V > Bloomberg::quantum::IThreadContext< RET >::get ( )

Get the future value associated with this context.

Note
Blocks until the future is ready or until an exception is thrown. Once this function returns, the future becomes invalidated (i.e. cannot be read again).

Implemented in Bloomberg::quantum::Context< RET >.

◆ getAt()

template<class RET >
template<class OTHER_RET >
NonBufferRetType< OTHER_RET > Bloomberg::quantum::IThreadContext< RET >::getAt ( int  num)

Get the future value from the 'num-th' continuation context.

Allowed range for num is [-1, total_continuations). -1 is equivalent of calling get() or getAt(total_continuations-1) on the last context in the chain (i.e. the context which is returned via end()). Position 0 represents the first future in the chain.

Template Parameters
OTHER_RETThe type of the future value associated with the 'num-th' context.
Parameters
[in]numThe number indicating which future to wait on.
Returns
The future value of the 'num-th' thread context.
Note
Blocks until the future is ready or until an exception is thrown. Once this function returns, the future is invalidated (i.e. cannot be read again).

Implemented in Bloomberg::quantum::Context< RET >.

◆ getCoroQueueIdRangeForAny()

template<class RET >
const std::pair< int, int > & Bloomberg::quantum::IThreadContext< RET >::getCoroQueueIdRangeForAny ( ) const

Gets the range [minQueueId, maxQueueId] of coroutine queueIds covered by IQueue::QueueId::Any by the Dispatcher.

Returns
queueIdRange The range of queueIds that IQueue::QueueId::Any covers

Implemented in Bloomberg::quantum::Context< RET >.

◆ getNumCoroutineThreads()

template<class RET >
int Bloomberg::quantum::IThreadContext< RET >::getNumCoroutineThreads ( ) const

Returns the number of underlying coroutine threads as specified in the dispatcher constructor. If -1 was passed than this number essentially indicates the number of cores.

Returns
The number of threads.
Note
Each thread services its own queueId, therefore this number can be used when assigning coroutines to a specific queue.

Implemented in Bloomberg::quantum::Context< RET >.

◆ getNumIoThreads()

template<class RET >
int Bloomberg::quantum::IThreadContext< RET >::getNumIoThreads ( ) const

Returns the number of underlying IO threads as specified in the dispatcher constructor.

Returns
The number of threads.
Note
Each thread services its own queueId, therefore this number can be used when assigning IO tasks to a specific queue.

Implemented in Bloomberg::quantum::Context< RET >.

◆ getRef()

template<class RET >
template<class V >
const NonBufferRetType< V > & Bloomberg::quantum::IThreadContext< RET >::getRef ( ) const

Get a reference the future value associated with this context.

Returns
A reference to the future value.
Note
Blocks until the future is ready or until an exception is thrown. Contrary to get(), this function does not invalidate the future and as such may be read again.

Implemented in Bloomberg::quantum::Context< RET >.

◆ getRefAt()

template<class RET >
template<class OTHER_RET >
const NonBufferRetType< OTHER_RET > & Bloomberg::quantum::IThreadContext< RET >::getRefAt ( int  num) const

Get a reference to the future value from the 'num-th' continuation context.

Allowed range for num is [-1, total_continuations). -1 is equivalent of calling get() or getAt(total_continuations-1) on the last context in the chain (i.e. the context which is returned via end()). Position 0 represents the first future in the chain.

Template Parameters
OTHER_RETThe type of the future value associated with the 'num-th' context.
Parameters
[in]numThe number indicating which future to wait on.
Returns
A reference to the future value of the 'num-th' thread context.
Note
Blocks until the future is ready or until an exception is thrown. Contrary to getAt() this function will not invalidate the future and as such it can be read again.

Implemented in Bloomberg::quantum::Context< RET >.

◆ onError() [1/2]

template<class RET>
template<class OTHER_RET , class FUNC , class ... ARGS>
ThreadContextPtr<OTHER_RET> Bloomberg::quantum::IThreadContext< RET >::onError ( FUNC &&  func,
ARGS &&...  args 
)

◆ onError() [2/2]

template<class RET>
template<class OTHER_RET = int, class FUNC , class ... ARGS>
IThreadContext<OTHER_RET>::Ptr Bloomberg::quantum::IThreadContext< RET >::onError ( FUNC &&  func,
ARGS &&...  args 
)

Posts a function to run asynchronously. This is the error handler for a continuation chain and acts as as a 'catch' clause.

This function is optional for the continuation chain and may be called at most once. If called, it must follow postFirst() or another then() method. This method will conditionally run if-and-only-if any previous functions in the continuation chain return an error or throw. When a function which is part of a continuation chain has an error, all subsequent then() methods are skipped and if onError() is provided it will be called. If there are no errors, this method is skipped.

Template Parameters
OTHER_RETType of future returned by this function.
FUNCCallable object type. Can be a standalone function, a method, an std::function, a functor generated via std::bind or a lambda. The signature of the callable object must strictly be 'int f(ThreadContext<RET>::Ptr, ...)'.
ARGSArgument types passed to FUNC.
Parameters
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
The function is non-blocking. The returned context can be used to chain further functions. Possible method calls following this are finally() and end().

Implemented in Bloomberg::quantum::Context< RET >, and Bloomberg::quantum::Context< RET >.

◆ pull()

template<class RET >
template<class V >
BufferRetType< V > Bloomberg::quantum::IThreadContext< RET >::pull ( bool &  isBufferClosed)

Pull a single value from the future buffer.

Template Parameters
BUFRepresents a class of type Buffer.
VThe type of value contained in Buffer.
Parameters
[out]isBufferClosedIndicates if this buffer is closed and no more Pull operations are allowed on it.
Returns
The next value pulled out from the front of the buffer.
Note
Method available for buffered futures only. Blocks until one value is retrieved from the buffer.

Implemented in Bloomberg::quantum::Context< RET >.

◆ push()

template<class RET >
template<class V , class >
void Bloomberg::quantum::IThreadContext< RET >::push ( V &&  value)

Push a single value into the promise buffer.

Template Parameters
BUFRepresents a class of type Buffer.
VThe type of value contained in Buffer.
Parameters
[in]valueValue to push at the end of the buffer.
Note
Method available for buffered futures only. Never blocks. Once the buffer is closed, no more Push operations are allowed.

Implemented in Bloomberg::quantum::Context< RET >.

◆ set()

template<class RET >
template<class V , class >
int Bloomberg::quantum::IThreadContext< RET >::set ( V &&  value)

Set the promised value associated with this context.

Template Parameters
VType of the promised value. This should be implicitly deduced by the compiler and should always == RET.
Parameters
[in]valueA reference to the value (l-value or r-value).
Note
Never blocks.
Returns
0 on success

Implemented in Bloomberg::quantum::Context< RET >.

◆ then() [1/2]

template<class RET>
template<class OTHER_RET , class FUNC , class ... ARGS>
ThreadContextPtr<OTHER_RET> Bloomberg::quantum::IThreadContext< RET >::then ( FUNC &&  func,
ARGS &&...  args 
)

◆ then() [2/2]

template<class RET>
template<class OTHER_RET = int, class FUNC , class ... ARGS>
IThreadContext<OTHER_RET>::Ptr Bloomberg::quantum::IThreadContext< RET >::then ( FUNC &&  func,
ARGS &&...  args 
)

Posts a function to run asynchronously.

Attention
Continuation methods are typically chained in the following manner and must follow the relative placement below. postFirst() and end() are the only mandatory methods. onError() and finally() can be called at most once, whereas then() may be called zero or more times.
IThreadContext<RET>::Ptr ctx = Dispatcher::postFirst()->then()->...->then()->onError()->finally()->end();

This function is optional for the continuation chain and may be called 0 or more times. If called, it must follow postFirst() or another then() method.

Template Parameters
OTHER_RETType of future returned by this function.
FUNCCallable object type. Can be a standalone function, a method, an std::function, a functor generated via std::bind or a lambda. The signature of the callable object must strictly be 'int f(ThreadContext<RET>::Ptr, ...)'.
ARGSArgument types passed to FUNC.
Parameters
[in]funcCallable object.
[in]argsVariable list of arguments passed to the callable object.
Note
This function is non-blocking and runs when all previous chained functions have completed. The returned context can be used to chain further functions. Possible method calls following this are then(), onError(), finally() and end().

Implemented in Bloomberg::quantum::Context< RET >, and Bloomberg::quantum::Context< RET >.

◆ wait()

template<class RET>
virtual void Bloomberg::quantum::IThreadContext< RET >::wait ( ) const
pure virtual

Waits for the future associated with this context to be ready.

Note
Blocks until the future is ready or until an exception is thrown.

Implements Bloomberg::quantum::IThreadContextBase.

Implemented in Bloomberg::quantum::Context< RET >.

◆ waitAll()

template<class RET>
virtual void Bloomberg::quantum::IThreadContext< RET >::waitAll ( ) const
pure virtual

Wait for all the futures in the continuation chain to be ready.

Note
Blocks until all future values are ready. If any future throws, the exception is swallowed.

Implements Bloomberg::quantum::IThreadContextBase.

Implemented in Bloomberg::quantum::Context< RET >.

◆ waitAt()

template<class RET>
virtual void Bloomberg::quantum::IThreadContext< RET >::waitAt ( int  num) const
pure virtual

Waits for the future in the 'num-th' continuation context to be ready.

Allowed range for num is [-1, total_continuations). -1 is equivalent of calling wait() or waitAt(total_continuations-1) on the last context in the chain (i.e. the context which is returned via end()). Position 0 represents the first future in the chain.

Parameters
[in]numThe number indicating which future to wait on.
Note
Blocks until the value is ready or an exception is thrown.

Implements Bloomberg::quantum::IThreadContextBase.

Implemented in Bloomberg::quantum::Context< RET >.

◆ waitFor()

template<class RET>
virtual std::future_status Bloomberg::quantum::IThreadContext< RET >::waitFor ( std::chrono::milliseconds  timeMs) const
pure virtual

Waits for the future associated with this context to be ready for a maximum of 'timeMs' milliseconds.

Parameters
[in]timeMsThe maximum amount of milliseconds to wait until the future value becomes ready.
Returns
'ready' if value was posted before duration expired or 'timeout' otherwise.
Note
Blocks until the value is ready, until 'timeMs' duration expires or until an exception is thrown.

Implements Bloomberg::quantum::IThreadContextBase.

Implemented in Bloomberg::quantum::Context< RET >.

◆ waitForAt()

template<class RET>
virtual std::future_status Bloomberg::quantum::IThreadContext< RET >::waitForAt ( int  num,
std::chrono::milliseconds  timeMs 
) const
pure virtual

Waits for the future in the 'num-th' continuation context to be ready for a maximum of 'timeMs' milliseconds.

Allowed range for num is [-1, total_continuations). -1 is equivalent of calling wait() or waitAt(total_continuations-1) on the last context in the chain (i.e. the context which is returned via end()). Position 0 represents the first future in the chain.

Parameters
[in]numThe number indicating which future to wait on.
[in]timeMsThe maximum amount of milliseconds to wait until the future value becomes ready.
Returns
'ready' if value was posted before duration expired or 'timeout' otherwise.
Note
Blocks until the value is ready, until 'timeMs' duration expires or until an exception is thrown.

Implements Bloomberg::quantum::IThreadContextBase.

Implemented in Bloomberg::quantum::Context< RET >.