Skip to content

Update ConcRT transformer class reference #5284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 1, 2025
Merged

Update ConcRT transformer class reference #5284

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 43 additions & 44 deletions docs/parallel/concrt/reference/transformer-class.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
---
description: "Learn more about: transformer Class"
title: "transformer Class"
description: "Learn more about: transformer Class"
ms.date: "11/04/2016"
f1_keywords: ["transformer", "AGENTS/concurrency::transformer", "AGENTS/concurrency::transformer::transformer", "AGENTS/concurrency::transformer::accept_message", "AGENTS/concurrency::transformer::consume_message", "AGENTS/concurrency::transformer::link_target_notification", "AGENTS/concurrency::transformer::propagate_message", "AGENTS/concurrency::transformer::propagate_to_any_targets", "AGENTS/concurrency::transformer::release_message", "AGENTS/concurrency::transformer::reserve_message", "AGENTS/concurrency::transformer::resume_propagation", "AGENTS/concurrency::transformer::send_message", "AGENTS/concurrency::transformer::supports_anonymous_source"]
helpviewer_keywords: ["transformer class"]
ms.assetid: eea71925-7043-4a92-bfd4-dbc0ece5d081
---
# transformer Class

Expand All @@ -13,17 +12,17 @@ A `transformer` messaging block is a single-target, multi-source, ordered `propa
## Syntax

```cpp
template<class _Input, class _Output>
template <class _Input, class _Output>
class transformer : public propagator_block<single_link_registry<ITarget<_Output>>,
multi_link_registry<ISource<_Input>>>;
```

### Parameters

*_Input*<br/>
*`_Input`*\
The payload type of the messages accepted by the buffer.

*_Output*<br/>
*`_Output`*\
The payload type of the messages stored and propagated out by the buffer.

## Members
Expand All @@ -32,27 +31,27 @@ The payload type of the messages stored and propagated out by the buffer.

|Name|Description|
|----------|-----------------|
|[transformer](#ctor)|Overloaded. Constructs a `transformer` messaging block.|
|[~transformer Destructor](#dtor)|Destroys the `transformer` messaging block.|
|[`transformer`](#ctor)|Overloaded. Constructs a `transformer` messaging block.|
|[`~transformer`](#dtor)|Destroys the `transformer` messaging block.|

### Protected Methods

|Name|Description|
|----------|-----------------|
|[accept_message](#accept_message)|Accepts a message that was offered by this `transformer` messaging block, transferring ownership to the caller.|
|[consume_message](#consume_message)|Consumes a message previously offered by the `transformer` and reserved by the target, transferring ownership to the caller.|
|[link_target_notification](#link_target_notification)|A callback that notifies that a new target has been linked to this `transformer` messaging block.|
|[propagate_message](#propagate_message)|Asynchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `propagate` method, when called by a source block.|
|[propagate_to_any_targets](#propagate_to_any_targets)|Executes the transformer function on the input messages.|
|[release_message](#release_message)|Releases a previous message reservation. (Overrides [source_block::release_message](source-block-class.md#release_message).)|
|[reserve_message](#reserve_message)|Reserves a message previously offered by this `transformer` messaging block. (Overrides [source_block::reserve_message](source-block-class.md#reserve_message).)|
|[resume_propagation](#resume_propagation)|Resumes propagation after a reservation has been released. (Overrides [source_block::resume_propagation](source-block-class.md#resume_propagation).)|
|[send_message](#send_message)|Synchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `send` method, when called by a source block.|
|[supports_anonymous_source](#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](itarget-class.md#supports_anonymous_source).)|
|[`accept_message`](#accept_message)|Accepts a message that was offered by this `transformer` messaging block, transferring ownership to the caller.|
|[`consume_message`](#consume_message)|Consumes a message previously offered by the `transformer` and reserved by the target, transferring ownership to the caller.|
|[`link_target_notification`](#link_target_notification)|A callback that notifies that a new target has been linked to this `transformer` messaging block.|
|[`propagate_message`](#propagate_message)|Asynchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `propagate` method, when called by a source block.|
|[`propagate_to_any_targets`](#propagate_to_any_targets)|Executes the transformer function on the input messages.|
|[`release_message`](#release_message)|Releases a previous message reservation. (Overrides [`source_block::release_message`](source-block-class.md#release_message).)|
|[`reserve_message`](#reserve_message)|Reserves a message previously offered by this `transformer` messaging block. (Overrides [`source_block::reserve_message`](source-block-class.md#reserve_message).)|
|[`resume_propagation`](#resume_propagation)|Resumes propagation after a reservation has been released. (Overrides [`source_block::resume_propagation`](source-block-class.md#resume_propagation).)|
|[`send_message`](#send_message)|Synchronously passes a message from an `ISource` block to this `transformer` messaging block. It is invoked by the `send` method, when called by a source block.|
|[`supports_anonymous_source`](#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`](itarget-class.md#supports_anonymous_source).)|

## Remarks

For more information, see [Asynchronous Message Blocks](../../../parallel/concrt/asynchronous-message-blocks.md).
For more information, see [Asynchronous Message Blocks](../asynchronous-message-blocks.md).

## Inheritance Hierarchy

Expand All @@ -72,7 +71,7 @@ For more information, see [Asynchronous Message Blocks](../../../parallel/concrt

**Namespace:** concurrency

## <a name="accept_message"></a> accept_message
## <a name="accept_message"></a> `accept_message`

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

Expand All @@ -82,14 +81,14 @@ virtual message<_Output>* accept_message(runtime_object_identity _MsgId);

### Parameters

*_MsgId*<br/>
*`_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.

## <a name="consume_message"></a> consume_message
## <a name="consume_message"></a> `consume_message`

Consumes a message previously offered by the `transformer` and reserved by the target, transferring ownership to the caller.

Expand All @@ -99,7 +98,7 @@ virtual message<_Output>* consume_message(runtime_object_identity _MsgId);

### Parameters

*_MsgId*<br/>
*`_MsgId`*\
The `runtime_object_identity` of the `message` object being consumed.

### Return Value
Expand All @@ -110,15 +109,15 @@ A pointer to the `message` object that the caller now has ownership of.

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

## <a name="link_target_notification"></a> link_target_notification
## <a name="link_target_notification"></a> `link_target_notification`

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

```cpp
virtual void link_target_notification(_Inout_ ITarget<_Output> *);
```

## <a name="propagate_message"></a> propagate_message
## <a name="propagate_message"></a> `propagate_message`

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

Expand All @@ -130,25 +129,25 @@ virtual message_status propagate_message(

### Parameters

*_PMessage*<br/>
*`_PMessage`*\
A pointer to the `message` object.

*_PSource*<br/>
*`_PSource`*\
A pointer to the source block offering the message.

### Return Value

A [message_status](concurrency-namespace-enums.md) indication of what the target decided to do with the message.

## <a name="propagate_to_any_targets"></a> propagate_to_any_targets
## <a name="propagate_to_any_targets"></a> `propagate_to_any_targets`

Executes the transformer function on the input messages.

```cpp
virtual void propagate_to_any_targets(_Inout_opt_ message<_Output> *);
```

## <a name="release_message"></a> release_message
## <a name="release_message"></a> `release_message`

Releases a previous message reservation.

Expand All @@ -158,10 +157,10 @@ virtual void release_message(runtime_object_identity _MsgId);

### Parameters

*_MsgId*<br/>
*`_MsgId`*\
The `runtime_object_identity` of the `message` object being released.

## <a name="reserve_message"></a> reserve_message
## <a name="reserve_message"></a> `reserve_message`

Reserves a message previously offered by this `transformer` messaging block.

Expand All @@ -171,7 +170,7 @@ virtual bool reserve_message(runtime_object_identity _MsgId);

### Parameters

*_MsgId*<br/>
*`_MsgId`*\
The `runtime_object_identity` of the `message` object being reserved.

### Return Value
Expand All @@ -182,15 +181,15 @@ The `runtime_object_identity` of the `message` object being reserved.

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

## <a name="resume_propagation"></a> resume_propagation
## <a name="resume_propagation"></a> `resume_propagation`

Resumes propagation after a reservation has been released.

```cpp
virtual void resume_propagation();
```

## <a name="send_message"></a> send_message
## <a name="send_message"></a> `send_message`

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

Expand All @@ -202,17 +201,17 @@ virtual message_status send_message(

### Parameters

*_PMessage*<br/>
*`_PMessage`*\
A pointer to the `message` object.

*_PSource*<br/>
*`_PSource`*\
A pointer to the source block offering the message.

### Return Value

A [message_status](concurrency-namespace-enums.md) indication of what the target decided to do with the message.

## <a name="supports_anonymous_source"></a> supports_anonymous_source
## <a name="supports_anonymous_source"></a> `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.

Expand All @@ -224,7 +223,7 @@ virtual bool supports_anonymous_source();

**`true`** because the block does not postpone offered messages.

## <a name="ctor"></a> transformer
## <a name="ctor"></a> `transformer`

Constructs a `transformer` messaging block.

Expand Down Expand Up @@ -263,19 +262,19 @@ transformer(

### Parameters

*_Func*<br/>
*`_Func`*\
A function that will be invoked for each accepted message.

*_PTarget*<br/>
*`_PTarget`*\
A pointer to a target block to link with the transformer.

*_Filter*<br/>
*`_Filter`*\
A filter function which determines whether offered messages should be accepted.

*_PScheduler*<br/>
*`_PScheduler`*\
The `Scheduler` object within which the propagation task for the `transformer` messaging block is scheduled.

*_PScheduleGroup*<br/>
*`_PScheduleGroup`*\
The `ScheduleGroup` object within which the propagation task for the `transformer` messaging block is scheduled. The `Scheduler` object used is implied by the schedule group.

### Remarks
Expand All @@ -286,7 +285,7 @@ The type `_Transform_method` is a functor with signature `_Output (_Input const

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

## <a name="dtor"></a> ~transformer
## <a name="dtor"></a> `~transformer`

Destroys the `transformer` messaging block.

Expand All @@ -296,5 +295,5 @@ Destroys the `transformer` messaging block.

## See also

[concurrency Namespace](concurrency-namespace.md)<br/>
[concurrency Namespace](concurrency-namespace.md)\
[call Class](call-class.md)