unbounded_buffer Class

An unbounded_buffer messaging block is a multi-target, multi-source, ordered propagator_block capable of storing an unbounded number of messages.

Syntax

template<
   class             _Type
>
class unbounded_buffer : public propagator_block<multi_link_registry<ITarget<            _Type>>, multi_link_registry<ISource<            _Type>>>;

Parameters

_Type
The payload type of the messages stored and propagated by the buffer.

Members

Public Constructors

Name	Description
unbounded_buffer	Overloaded. Constructs an unbounded_buffer messaging block.
~unbounded_buffer Destructor	Destroys the unbounded_buffer messaging block.

Public Methods

Name	Description
dequeue	Removes an item from the unbounded_buffer messaging block.
enqueue	Adds an item to the unbounded_buffer messaging block.

Protected Methods

Name	Description
accept_message	Accepts a message that was offered by this unbounded_buffer messaging block, transferring ownership to the caller.
consume_message	Consumes a message previously offered by the unbounded_buffer 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 unbounded_buffer messaging block.
process_input_messages	Places the message _PMessage in this unbounded_buffer messaging block and tries to offer it to all of the linked targets.
propagate_message	Asynchronously passes a message from an ISource block to this unbounded_buffer messaging block. It is invoked by the propagate method, when called by a source block.
propagate_output_messages	Places the message _PMessage in this unbounded_buffer messaging block and tries to offer it to all of the linked targets. (Overrides source_block::propagate_output_messages.)
release_message	Releases a previous message reservation. (Overrides source_block::release_message.)
reserve_message	Reserves a message previously offered by this unbounded_buffer messaging block. (Overrides source_block::reserve_message.)
resume_propagation	Resumes propagation after a reservation has been released. (Overrides source_block::resume_propagation.)
send_message	Synchronously passes a message from an ISource block to this unbounded_buffer messaging block. It is invoked by the send method, when called by a source block.
supports_anonymous_source	Overrides the supports_anonymous_source method to indicate that this block can accept messages offered to it by a source that is not linked. (Overrides ITarget::supports_anonymous_source.)

For more information, see Asynchronous Message Blocks.

Inheritance Hierarchy

ISource

ITarget

source_block

propagator_block

unbounded_buffer

Requirements

Header: agents.h

Namespace: concurrency

accept_message

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

virtual message<_Type> * 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 unbounded_buffer messaging block and reserved by the target, transferring ownership to the caller.

virtual message<_Type> * 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.

dequeue

Removes an item from the unbounded_buffer messaging block.

_Type dequeue();

Return Value

The payload of the message removed from the unbounded_buffer.

enqueue

Adds an item to the unbounded_buffer messaging block.

bool enqueue(
   _Type const&                 _Item
);

Parameters

_Item
The item to add.

Return Value

true if the item was accepted, false otherwise.

link_target_notification

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

virtual void link_target_notification(
   _Inout_ ITarget<_Type> *                 _PTarget
);

Parameters

_PTarget
A pointer to the newly linked target.

propagate_message

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

virtual message_status propagate_message(
   _Inout_ message<_Type> *                 _PMessage,
   _Inout_ ISource<_Type> *                 _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_output_messages

Places the message _PMessage in this unbounded_buffer messaging block and tries to offer it to all of the linked targets.

virtual void propagate_output_messages();

Remarks

If another message is already ahead of this one in the unbounded_buffer, propagation to linked targets will not occur until any earlier messages have been accepted or consumed. The first linked target to successfully accept or consume the message takes ownership, and no other target can then get the message.

process_input_messages

Places the message _PMessage in this unbounded_buffer messaging block and tries to offer it to all of the linked targets.

virtual void process_input_messages(
   _Inout_ message<_Type> *                 _PMessage
);

Parameters

_PMessage
A pointer to the message that is to be processed.

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 unbounded_buffer messaging block.

virtual bool reserve_message(
   runtime_object_identity                 _MsgId
);

Parameters

_MsgId
The runtime_object_identity of the message object being reserved.

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();

send_message

Synchronously passes a message from an ISource block to this unbounded_buffer messaging block. It is invoked by the send method, when called by a source block.

virtual message_status send_message(
   _Inout_ message<_Type> *                 _PMessage,
   _Inout_ ISource<_Type> *                 _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.

supports_anonymous_source

Overrides the supports_anonymous_source method to indicate that this block can accept messages offered to it by a source that is not linked.

virtual bool supports_anonymous_source();

Return Value

true because the block does not postpone offered messages.

unbounded_buffer

Constructs an unbounded_buffer messaging block.

unbounded_buffer();

unbounded_buffer(
   filter_method const&                 _Filter
);

unbounded_buffer(
   Scheduler&                 _PScheduler
);

unbounded_buffer(
   Scheduler&                 _PScheduler,
   filter_method const&                 _Filter
);

unbounded_buffer(
   ScheduleGroup&                 _PScheduleGroup
);

unbounded_buffer(
   ScheduleGroup&                 _PScheduleGroup,
   filter_method const&                 _Filter
);

Parameters

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

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

_PScheduleGroup
The ScheduleGroup object within which the propagation task for the unbounded_buffer 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 (_Type const &) which is invoked by this unbounded_buffer messaging block to determine whether or not it should accept an offered message.

~unbounded_buffer

Destroys the unbounded_buffer messaging block.

~unbounded_buffer();

See also

concurrency Namespace
overwrite_buffer Class
single_assignment Class