Edit

join Class

  • Article

A join messaging block is a single-target, multi-source, ordered propagator_block which combines together messages of type T from each of its sources.

Syntax

template<class T,
    join_type _Jtype = non_greedy>
class join : public propagator_block<single_link_registry<ITarget<std::vector<T>>>,
    multi_link_registry<ISource<T>>>;

Parameters

T
The payload type of the messages joined and propagated by the block.

_Jtype
The kind of join block this is, either greedy or non_greedy

Members

Public Constructors

Name Description
join Overloaded. Constructs a join messaging block.
~join Destructor Destroys the join block.

Protected Methods

Name Description
accept_message Accepts a message that was offered by this join messaging block, transferring ownership to the caller.
consume_message Consumes a message previously offered by the join messaging block and reserved by the target, transferring ownership to the caller.
link_target_notification A callback that notifies that a new target has been linked to this join messaging block.
propagate_message Asynchronously passes a message from an ISource block to this join messaging block. It is invoked by the propagate method, when called by a source block.
propagate_to_any_targets Constructs an output message containing an input message from each source when they have all propagated a message. Sends this output message out to each of its targets.
release_message Releases a previous message reservation. (Overrides source_block::release_message.)
reserve_message Reserves a message previously offered by this join messaging block. (Overrides source_block::reserve_message.)
resume_propagation Resumes propagation after a reservation has been released. (Overrides source_block::resume_propagation.)

Remarks

For more information, see Asynchronous Message Blocks.

Inheritance Hierarchy

ISource

ITarget

source_block

propagator_block

join

Requirements

Header: agents.h

Namespace: concurrency

accept_message

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

virtual message<_OutputType>* accept_message(runtime_object_identity _MsgId);

Parameters

_MsgId
The runtime_object_identity of the offered message object.

Return Value

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

consume_message

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

virtual message<_OutputType>* consume_message(runtime_object_identity _MsgId);

Parameters

_MsgId
The runtime_object_identity of the message object being consumed.

Return Value

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

Remarks

Similar to accept, but is always preceded by a call to reserve.

join

Constructs a join messaging block.

join(
    size_t _NumInputs);

join(
    size_t _NumInputs,
    filter_method const& _Filter);

join(
    Scheduler& _PScheduler,
    size_t _NumInputs);

join(
    Scheduler& _PScheduler,
    size_t _NumInputs,
    filter_method const& _Filter);

join(
    ScheduleGroup& _PScheduleGroup,
    size_t _NumInputs);

join(
    ScheduleGroup& _PScheduleGroup,
    size_t _NumInputs,
    filter_method const& _Filter);

Parameters

_NumInputs
The number of inputs this join block will be allowed.

_Filter
A filter function which determines whether offered messages should be accepted.

_PScheduler
The Scheduler object within which the propagation task for the join messaging block is scheduled.

_PScheduleGroup
The ScheduleGroup object within which the propagation task for the join messaging block is scheduled. The Scheduler object used is implied by the schedule group.

Remarks

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

The type filter_method is a functor with signature bool (T const &) which is invoked by this join messaging block to determine whether or not it should accept an offered message.

~join

Destroys the join block.

~join();

A callback that notifies that a new target has been linked to this join messaging block.

virtual void link_target_notification(_Inout_ ITarget<std::vector<T>> *);

propagate_message

Asynchronously passes a message from an ISource block to this join messaging block. It is invoked by the propagate method, when called by a source block.

message_status propagate_message(
    _Inout_ message<T>* _PMessage,
    _Inout_ ISource<T>* _PSource);

Parameters

_PMessage
A pointer to the message object.

_PSource
A pointer to the source block offering the message.

Return Value

A message_status indication of what the target decided to do with the message.

propagate_to_any_targets

Constructs an output message containing an input message from each source when they have all propagated a message. Sends this output message out to each of its targets.

void propagate_to_any_targets(_Inout_opt_ message<_OutputType> *);

release_message

Releases a previous message reservation.

virtual void release_message(runtime_object_identity _MsgId);

Parameters

_MsgId
The runtime_object_identity of the message object being released.

reserve_message

Reserves a message previously offered by this join messaging block.

virtual bool reserve_message(runtime_object_identity _MsgId);

Parameters

_MsgId
The runtime_object_identity of the offered message object.

Return Value

true if the message was successfully reserved, false otherwise.

Remarks

After reserve is called, if it returns true, either consume or release must be called to either take or release ownership of the message.

resume_propagation

Resumes propagation after a reservation has been released.

virtual void resume_propagation();

See also

concurrency Namespace
choice Class
multitype_join Class