PHP Advanced Dispatches

Home

Contents

• Advanced Dispatches
• Dispatch Features
  • Results and Stateful Dispatches
  • Consumable Dispatches

Advanced Dispatches

Dispatches, as explained here, are objects that carry information along chains within N2f. Here we'll explain a bit more of the advanced functionality available to Dispatches and offer some examples to show how they can be useful.

Dispatch Features

There are two (and a half) features which make up the advanced functionality:

• Results - It is possible to store results inside a dispatch for retrieval at a later point in the chain or after chain processing is complete.
  • Stateful Dispatches - Enabling this will allow multiple results to be stored, preserving any information stored by nodes.
• Consumable Dispatches - Dispatches can be made 'consumable' so that a node can mark them as 'consumed' and stop traversal of the chain.

Results and Stateful Dispatches

Sometimes, when building your chains, you might expect to get information back when a chain has been traversed. The \N2f\DispatchBase abstract class comes with the ability to store a result inside the Dispatch so that it can be accessed later. A simple example of this would be easiest to show inside a theoretical Node:

class MyNode extends \N2f\NodeBase {
	// ...

	public function Process($Sender, \N2f\DispatchBase &$Dispatch) {
		$Dispatch->SetResult("My arbitrary result.");

		return;
	}
}

Given the above, if the MyNode node processes a dispatch, after traversal the string "My arbitrary result." will be available by calling GetResults() on the dispatch. GetResults() will always return an array (explained momentarily), and the result will be the first element in the array.

Additionally, dispatches can be made 'stateful' so that they hold multiple results, keeping results from being overwritten by separate nodes. This is a simple toggle on the dispatch class, and explains why GetResults() on dispatches will always return an array:

class MyDispatch extends \N2f\DispatchBase {
	public function Initialize($Input) {
		$this->MakeStateful();
		$this->MakeValid();

		return;
	}
}

Now, any use of SetResult() on a dispatch of the type MyDispatch will simply add the results as new elements to the internal array returned by GetResults().

Consumable Dispatches

Certain types of chains will be looking for a "first come, first serve" behavior by the chain. This is supported by marking a dispatch as 'consumable' at initialization.

class MyDispatch extends \N2f\DispatchBase {
	public function Initialize($Input) {
		$this->MakeConsumable();
		$this->MakeValid();

		return;
	}
}

Now, by calling Consume() on the dispatch, a node is able to stop further traversal of the chain.