Concurrency::choice< _Type > Class Template Reference

A choice messaging block is a multi-source, single-target block that represents a control-flow interaction with a set of sources. The choice block will wait for any one of multiple sources to produce a message and will propagate the index of the source that produced the message. More...

#include <agents.h>

Inheritance diagram for Concurrency::choice< _Type >:

Public Types
typedef _Type	type
	A type alias for _Type . More...
Public Types inherited from Concurrency::ISource< size_t >
typedef size_t	source_type
	A type alias for _Type . More...

Public Member Functions
	choice (_Type _Tuple)
	Constructs a choice messaging block. More...
	choice (choice &&_Choice)
	Constructs a choice messaging block. More...
	~choice ()
	Destroys the choice messaging block. More...
bool	has_value () const
	Checks whether this choice messaging block has been initialized with a value yet. More...
size_t	index ()
	Returns an index into the tuple representing the element selected by the choice messaging block. More...
template<typename _Payload_type >
_Payload_type const &	value ()
	Gets the message whose index was selected by the choice messaging block. More...
virtual void	link_target (_Inout_ ITarget< size_t > *_PTarget)
	Links a target block to this choice messaging block. More...
virtual void	unlink_target (_Inout_ ITarget< size_t > *_PTarget)
	Unlinks a target block from this choice messaging block. More...
virtual void	unlink_targets ()
	Unlinks all targets from this choice messaging block. More...
virtual message< size_t > *	accept (runtime_object_identity _MsgId, _Inout_ ITarget< size_t > *_PTarget)
	Accepts a message that was offered by this choice block, transferring ownership to the caller. More...
virtual bool	reserve (runtime_object_identity _MsgId, _Inout_ ITarget< size_t > *_PTarget)
	Reserves a message previously offered by this choice messaging block. More...
virtual message< size_t > *	consume (runtime_object_identity _MsgId, _Inout_ ITarget< size_t > *_PTarget)
	Consumes a message previously offered by this choice messaging block and successfully reserved by the target, transferring ownership to the caller. More...
virtual void	release (runtime_object_identity _MsgId, _Inout_ ITarget< size_t > *_PTarget)
	Releases a previous successful message reservation. More...
virtual void	acquire_ref (_Inout_ ITarget< size_t > *_PTarget)
	Acquires a reference count on this choice messaging block, to prevent deletion. More...
virtual void	release_ref (_Inout_ ITarget< size_t > *_PTarget)
	Releases a reference count on this choice messaging block. More...
Public Member Functions inherited from Concurrency::ISource< size_t >
virtual	~ISource ()
	Destroys the ISource object. More...

Private Types
template<int _Index>
using	_Reserving_node_source_type = _Reserving_node< typename std::remove_pointer_t< std::tuple_element_t< _Index, _Type >>::source_type >

Private Member Functions
template<int _Index>
void	_Initialize_choices ()
	Constructs and initializes a _Reserving_node for each tuple messaging block passed in. More...
template<>
void	_Initialize_choices ()
	Provides a sentinel template specialization for _Initialize_choices recursive template expansion. More...
template<int _Index>
void	_Delete_choices ()
	Deletes all _Reserving_node elements that were created in _Initialize_choices. More...
template<>
void	_Delete_choices ()
	Provides a sentinel template specialization for _Delete_choices recursive template expansion. More...
choice const &	operator= (choice const &)
	choice (choice const &)

Private Attributes
void *	_M_pSourceChoices [std::tuple_size< _Type >::value]
single_assignment< size_t > *	_M_pSingleAssignment
_Type	_M_sourceTuple
Scheduler *	_M_pScheduler
ScheduleGroup *	_M_pScheduleGroup

Additional Inherited Members
Protected Member Functions inherited from Concurrency::ISource< size_t >
void	_Invoke_link_source (ITarget< size_t > *_PLinkFrom)
	Links this source to a target. More...
void	_Invoke_unlink_source (ITarget< size_t > *_PUnlinkFrom)
	Unlinks this source from a target. More...

Detailed Description

template<class _Type>
class Concurrency::choice< _Type >

A choice messaging block is a multi-source, single-target block that represents a control-flow interaction with a set of sources. The choice block will wait for any one of multiple sources to produce a message and will propagate the index of the source that produced the message.

Template Parameters

_Type

A tuple-based type representing the payloads of the input sources.

The choice block ensures that only one of the incoming messages is consumed.

For more information, see Asynchronous Message Blocks.

See also

join Class, single_assignment Class, make_choice Function, tuple Class

Member Typedef Documentation

template<class _Type >

template<int _Index>

using Concurrency::choice< _Type >::_Reserving_node_source_type = _Reserving_node<typename std::remove_pointer_t<std::tuple_element_t<_Index, _Type>>::source_type>

private

template<class _Type >

typedef _Type Concurrency::choice< _Type >::type

A type alias for _Type .

Constructor & Destructor Documentation

template<class _Type >

Concurrency::choice< _Type >::choice ( _Type  _Tuple )

inlineexplicit

Constructs a choice messaging block.

Parameters

_Tuple

A tuple of sources for the choice.

The runtime uses the default scheduler if you do not specify the _PScheduler or _PScheduleGroup parameters.

Move construction is not performed under a lock, which means that it is up to the user to make sure that there are no light-weight tasks in flight at the time of moving. Otherwise, numerous races can occur, leading to exceptions or inconsistent state.

See also

Scheduler Class, ScheduleGroup Class

                                  : _M_sourceTuple(_Tuple), _M_pScheduler(NULL), _M_pScheduleGroup(NULL)
    {
        _M_pSingleAssignment = new single_assignment<size_t>();
        _Initialize_choices<0>();
    }

template<class _Type >

Concurrency::choice< _Type >::choice ( choice< _Type > &&  _Choice )

inline

Constructs a choice messaging block.

Parameters

_Choice

A choice messaging block to copy from. Note that the original object is orphaned, making this a move constructor.

The runtime uses the default scheduler if you do not specify the _PScheduler or _PScheduleGroup parameters.

Move construction is not performed under a lock, which means that it is up to the user to make sure that there are no light-weight tasks in flight at the time of moving. Otherwise, numerous races can occur, leading to exceptions or inconsistent state.

See also

Scheduler Class, ScheduleGroup Class

    {
        // Copy scheduler group or scheduler to the new object.
        _M_pScheduleGroup = _Choice._M_pScheduleGroup;
        _M_pScheduler = _Choice._M_pScheduler;

        // Single assignment is heap allocated, so simply copy the pointer. If it already has
        // a value, it will be preserved.
        _M_pSingleAssignment = _Choice._M_pSingleAssignment;
        _Choice._M_pSingleAssignment = NULL;

        // Invoke copy assignment for tuple to copy pointers to message blocks.
        _M_sourceTuple = _Choice._M_sourceTuple;

        // Copy the pointers to order nodes to a new object and zero out in the old object.
        memcpy(_M_pSourceChoices, _Choice._M_pSourceChoices, sizeof(_M_pSourceChoices));
        memset(_Choice._M_pSourceChoices, 0, sizeof(_M_pSourceChoices));
    }

template<class _Type >

Concurrency::choice< _Type >::~choice ( )

inline

Destroys the choice messaging block.

    {
        delete _M_pSingleAssignment;
        _Delete_choices<0>();
    }

template<class _Type >

Concurrency::choice< _Type >::choice ( choice< _Type > const &  )

private

Member Function Documentation

template<class _Type >

template<int _Index>

void Concurrency::choice< _Type >::_Delete_choices ( )

inlineprivate

Deletes all _Reserving_node elements that were created in _Initialize_choices.

The highest-number index of the choice's sources

    {
        delete static_cast<_Reserving_node_source_type<_Index> *>(_M_pSourceChoices[_Index]);
        _M_pSourceChoices[_Index] = NULL;
        _Delete_choices<_Index + 1>();
    }

template<class _Type >

template<>

void Concurrency::choice< _Type >::_Delete_choices ( )

inlineprivate

Provides a sentinel template specialization for _Delete_choices recursive template expansion.

    {
    }

template<class _Type >

template<int _Index>

void Concurrency::choice< _Type >::_Initialize_choices ( )

inlineprivate

Constructs and initializes a _Reserving_node for each tuple messaging block passed in.

The highest-number index of the choice's sources

    {
        std::tuple_element_t<_Index, _Type> _Item = std::get<_Index>(_M_sourceTuple);
        _Reserving_node_source_type<_Index> * _Order_node_element = NULL;

        if (_M_pScheduleGroup != NULL)
        {
            _Order_node_element = new _Reserving_node_source_type<_Index>(*_M_pScheduleGroup, _Item, _Index);
        }
        else if (_M_pScheduler != NULL)
        {
            _Order_node_element = new _Reserving_node_source_type<_Index>(*_M_pScheduler, _Item, _Index);
        }
        else
        {
            _Order_node_element = new _Reserving_node_source_type<_Index>(_Item, _Index);
        }

        _M_pSourceChoices[_Index] = _Order_node_element;
        _Order_node_element->link_target(_M_pSingleAssignment);
        _Initialize_choices<_Index + 1>();
    }

template<class _Type >

template<>

void Concurrency::choice< _Type >::_Initialize_choices ( )

inlineprivate

Provides a sentinel template specialization for _Initialize_choices recursive template expansion.

    {
    }

template<class _Type >

virtual message<size_t>* Concurrency::choice< _Type >::accept ( runtime_object_identity  _MsgId, _Inout_ ITarget< size_t > *  _PTarget  )

inlinevirtual

Accepts a message that was offered by this choice block, transferring ownership to the caller.

Parameters

_MsgId	The runtime_object_identity of the offered message object.
_PTarget	A pointer to the target block that is calling the accept method.

Returns

A pointer to the message that the caller now has ownership of.

Implements Concurrency::ISource< size_t >.

    {
        return _M_pSingleAssignment->accept(_MsgId, _PTarget);
    }

template<class _Type >

virtual void Concurrency::choice< _Type >::acquire_ref ( _Inout_ ITarget< size_t > *  _PTarget )

inlinevirtual

Acquires a reference count on this choice messaging block, to prevent deletion.

Parameters

_PTarget

A pointer to the target block that is calling this method.

This method is called by an ITarget object that is being linked to this source during the link_target method.

Implements Concurrency::ISource< size_t >.

    {
        _M_pSingleAssignment->acquire_ref(_PTarget);
    }

template<class _Type >

virtual message<size_t>* Concurrency::choice< _Type >::consume ( runtime_object_identity  _MsgId, _Inout_ ITarget< size_t > *  _PTarget  )

inlinevirtual

Consumes a message previously offered by this choice messaging block and successfully reserved by the target, transferring ownership to the caller.

Parameters

_MsgId	The runtime_object_identity of the reserved message object.
_PTarget	A pointer to the target block that is calling the consume method.

Returns

A pointer to the message object that the caller now has ownership of.

The consume method is similar to accept, but must always be preceded by a call to reserve that returned true.

Implements Concurrency::ISource< size_t >.

    {
        return _M_pSingleAssignment->consume(_MsgId, _PTarget);
    }

template<class _Type >

bool Concurrency::choice< _Type >::has_value ( ) const

inline

Checks whether this choice messaging block has been initialized with a value yet.

Returns

true if the block has received a value, false otherwise.

    {
        return _M_pSingleAssignment->has_value();
    }

template<class _Type >

size_t Concurrency::choice< _Type >::index ( )

inline

Returns an index into the tuple representing the element selected by the choice messaging block.

Returns

The message index.

The message payload can be extracted using the get method.

    {
        return _M_pSingleAssignment->value();
    }

template<class _Type >

virtual void Concurrency::choice< _Type >::link_target ( _Inout_ ITarget< size_t > *  _PTarget )

inlinevirtual

Links a target block to this choice messaging block.

Parameters

_PTarget

A pointer to an ITarget block to link to this choice messaging block.

Implements Concurrency::ISource< size_t >.

    {
        _M_pSingleAssignment->link_target(_PTarget);
    }

template<class _Type >

choice const& Concurrency::choice< _Type >::operator= ( choice< _Type > const &  )

private

template<class _Type >

virtual void Concurrency::choice< _Type >::release ( runtime_object_identity  _MsgId, _Inout_ ITarget< size_t > *  _PTarget  )

inlinevirtual

Releases a previous successful message reservation.

Parameters

_MsgId	The runtime_object_identity of the message object being released.
_PTarget	A pointer to the target block that is calling the release method.

Implements Concurrency::ISource< size_t >.

    {
        _M_pSingleAssignment->release(_MsgId, _PTarget);
    }

template<class _Type >

virtual void Concurrency::choice< _Type >::release_ref ( _Inout_ ITarget< size_t > *  _PTarget )

inlinevirtual

Releases a reference count on this choice messaging block.

Parameters

_PTarget

A pointer to the target block that is calling this method.

This method is called by an ITarget object that is being unlinked from this source. The source block is allowed to release any resources reserved for the target block.

Implements Concurrency::ISource< size_t >.

    {
        _M_pSingleAssignment->release_ref(_PTarget);
    }

template<class _Type >

virtual bool Concurrency::choice< _Type >::reserve ( runtime_object_identity  _MsgId, _Inout_ ITarget< size_t > *  _PTarget  )

inlinevirtual

Reserves a message previously offered by this choice messaging block.

Parameters

_MsgId	The runtime_object_identity of the message object being reserved.
_PTarget	A pointer to the target block that is calling the reserve method.

Returns

true if the message was successfully reserved, false otherwise. Reservations can fail for many reasons, including: the message was already reserved or accepted by another target, the source could deny reservations, and so forth.

After you call reserve, if it succeeds, you must call either consume or release in order to take or give up possession of the message, respectively.

Implements Concurrency::ISource< size_t >.

    {
        return _M_pSingleAssignment->reserve(_MsgId, _PTarget);
    }

template<class _Type >

virtual void Concurrency::choice< _Type >::unlink_target ( _Inout_ ITarget< size_t > *  _PTarget )

inlinevirtual

Unlinks a target block from this choice messaging block.

Parameters

_PTarget

A pointer to an ITarget block to unlink from this choice messaging block.

Implements Concurrency::ISource< size_t >.

    {
        _M_pSingleAssignment->unlink_target(_PTarget);
    }

template<class _Type >

virtual void Concurrency::choice< _Type >::unlink_targets ( )

inlinevirtual

Unlinks all targets from this choice messaging block.

This method does not need to be called from the destructor because destructor for the internal single_assignment block will unlink properly.

Implements Concurrency::ISource< size_t >.

    {
        _M_pSingleAssignment->unlink_targets();
    }

template<class _Type >

template<typename _Payload_type >

_Payload_type const& Concurrency::choice< _Type >::value ( )

inline

Gets the message whose index was selected by the choice messaging block.

Template Parameters

_Payload_type

The type of the message payload.

Returns

The payload of the message.

Because a choice messaging block can take inputs with different payload types, you must specify the type of the payload at the point of retrieval. You can determine the type based on the result of the index method.

    {
        return static_cast<_Reserving_node<_Payload_type> *>(_M_pSourceChoices[_M_pSingleAssignment->value()])->value();
    }

Member Data Documentation

template<class _Type >

ScheduleGroup* Concurrency::choice< _Type >::_M_pScheduleGroup

private

template<class _Type >

Scheduler* Concurrency::choice< _Type >::_M_pScheduler

private

template<class _Type >

single_assignment<size_t>* Concurrency::choice< _Type >::_M_pSingleAssignment

private

template<class _Type >

void* Concurrency::choice< _Type >::_M_pSourceChoices[std::tuple_size< _Type >::value]

private

template<class _Type >

_Type Concurrency::choice< _Type >::_M_sourceTuple

private

---

The documentation for this class was generated from the following file:

• VS2017/inc/agents.h