Operating

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

You can easily operate on your chain via a C++ lambda and this is how you do it:

Chain->Operate([](FMyTrait Trait)
{
    ...
});

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:

SolidChain->Operate([](FMyTrait& Trait)
{
    ...
});

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

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:

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

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.

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:

Chain->Operate([](FSubjectHandle Subject, FMyTrait Trait)
{
    ...
});

This, of course, has to match the solidity of the chain. So for a solid chain this would be:

SolidChain->Operate([](FSolidSubjectHandle Subject, FMyTrait& Trait)
{
    ...
});

You can actually ask for different contextual information within the loop. For example:

Chain->Operate([](const FChain* Chain, const FChainCursor& Cursor, ISubjective* Subjective, FMyTrait Trait, UMyDetail* Detail)
{
    ...
});

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 GetChainSlotIndex() method of the corresponding Cursor type, which can also be delivered using the aforementioned means:

SolidChain->Operate([](FPlacementTrait& Placement, const FSolidChainCursor& Cursor)
{
	Placement.Number = Cursor.GetChainSlotIndex();
});

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 method.

For example:

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