en:toolworks:docs:apparatus:operating [Turbopedia]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Operating ======

The newer and more robust way of handle your chains is through the process called operating.

===== C++ Workflow =====

==== Using a Lambda ====

You can easily operate on your chain via a [[cpp>language/lambda|C++ lambda]] and this is how you do it:
<code cpp>
Chain->Operate([](FMyTrait Trait)
{
    ...
});
</code>

Note that you're not allowed to acquire a reference to the trait while processing a non-solid chain, only its copy.
So in order to operate on a solid chain, you could do something like this:

<code cpp>
SolidChain->Operate([](FMyTrait& Trait)
{
    ...
});
</code>

Now you can change the properties (fields) of the trait directly, without copying involved.

==== Concurrency ====

Solid Chains also support a special type of operating - a multi-threaded one.
The function to call is explicitly named with a ''Concurrently'' prefix and
accepts two more arguments: the maximum number of tasks to utilize and the minimum number
of slots per each such task. For example:

<code cpp>
SolidChain->OperateConcurrently([](FMyTrait& Trait)
{
    ...
}, 4, 32);
</code>

The second parameter helps to also limit the number of tasks. If there are too little slots
available, excessive tasks not needed for that quantity won't be queued at all.

==== Dependency Injection ====

One great thing about operating is that the function arguments are actually resolved
and delivered automatically to your logic. For example, if you also modify the currently 
iterated subject, just specify the Subject handle in the very declaration of the routine:<code cpp>
Chain->Operate([](FSubjectHandle Subject, FMyTrait Trait)
{
    ...
});
</code>

This, of course, has to match the solidity of the chain. So for a solid chain this would be:<code cpp>
SolidChain->Operate([](FSolidSubjectHandle Subject, FMyTrait& Trait)
{
    ...
});
</code>

You can actually ask for different contextual information within the loop. For example:<code cpp>
Chain->Operate([](const FChain* Chain, const FChainCursor& Cursor, ISubjective* Subjective, FMyTrait Trait, UMyDetail* Detail)
{
    ...
});
</code>

==== Current Iteration Index ====

Just in case you need to know the number of the current iterated Slot (i.e. Subject's place within the chain), use the dedicated [[appi>struct_t_chain_1_1_f_cursor.html#a18005eddb3a624bdabb76475c3863751|GetChainSlotIndex()]] method of the corresponding Cursor type, which can also be delivered using the [[#argument_delivery|aforementioned means]]:<code cpp>
SolidChain->Operate([](FPlacementTrait& Placement, const FSolidChainCursor& Cursor)
{
	Placement.Number = Cursor.GetChainSlotIndex();
});
</code>

==== Stopping ====

While conceptually not very clean it is sometime useful to stop the actual processing (iterating) of the chain
prematurely, manually. This can be easily accomplished with a dedicated [[appi>struct_t_chain.html#aec97fe73be3d6d9f4c279c7427ed99d6|method]].

For example:<code cpp>
int32 Counter = 0;
Chain->Operate([&Counter](const FChain* Chain, FMyTrait Trait)
{
    if (Counter > 100)
    {
        Chain->StopIterating();
        // Return explicitly, so the counter doesn't get incremented on the current iteration:
        return;
    }
    Counter += Trait.Value;
});
</code>

==== Direct Mechanism Operating ====

The Operating simplification goes as far as actually Operating on a Mechanism directly, like so:<code cpp>
Mechanism->Operate([](FGlowing Glowing, FHelmet Helmet)
{
    ...
});
</code>

This way the [[en:toolworks:docs:apparatus:filter|Filtering]] and the [[en:toolworks:docs:apparatus:enchaining|Enchaining]] is done automatically under the hood, deriving the necessary Components from the lambda arguments.

You can of course supply the Filter specification explicitly, overriding it.

So for example, if you want to specify an additional [[en:toolworks:docs:apparatus:trait|Trait]] and a [[en:toolworks:docs:apparatus:flag|Flagmark]] condition, do it like so:<code cpp>
Mechanism->Operate(FFilter::Make<FGlowing, FHelmet, FHero>(FM_Z), [](FGlowing Glowing, FHelmet Helmet)
{
    ...
});
</code>

The direct Operating mode is smart enough to deduce the type of the Chain used within the Operating process, so if you specify a reference to a Trait and/or a Solid Subject handle in your arguments list, the technique will essentially produce a [[en:toolworks:docs:apparatus:solidity|Solid]] iterating:<code cpp>
Mechanism->Operate([](FSolidSubjectHandle Subject, FGlowing& Glowing, FHelmet& Helmet)
{
    ...
});
</code>

You can still specify the Chain type explicitly as a first template argument to a method:<code cpp>
Mechanism->Operate<FSolidChain>([](FGlowing Glowing, FHelmet Helmet)
{
    // You logic within Solid semantics:
    ...
});
</code>

Concurrency variants are also provided by the direct interface:<code cpp>
Mechanism->OperateConcurrently([](FSolidSubjectHandle Subject, FGlowing& Glowing, FHelmet& Helmet)
{
    ...
}, /*Maximum number of threads=*/4, /*Minimum number of Subjects=*/16);
</code>