Struct Builder 

pub struct Builder<'w, 's, 'a> { /* private fields */ }

Device used for building a workflow. Simply pass a mutable borrow of this into any functions which ask for it.

Note that each scope has its own Builder, and a panic will occur if a Builder gets used in the wrong scope. As of right now there is no known way to trick the compiler into using a Builder in the wrong scope, but please open an issue with a minimal reproducible example if you find a way to make it panic.

Implementations

impl<'w, 's, 'a> Builder<'w, 's, 'a>

pub fn chain<'b, Response: 'static + Send + Sync>( &'b mut self, output: Output<Response>, ) -> Chain<'w, 's, 'a, 'b, Response>

Begin building a chain of operations off of an output.

pub fn create_node<P: Provider>( &mut self, provider: P, ) -> Node<P::Request, P::Response, P::Streams>

where P::Request: 'static + Send + Sync, P::Response: 'static + Send + Sync, P::Streams: StreamPack,

Create a node for a provider. This will give access to an input slot, an output slots, and a pack of stream outputs which can all be connected to other nodes.

pub fn create_map_block<T, U>( &mut self, f: impl FnMut(T) -> U + 'static + Send + Sync, ) -> Node<T, U, ()>

where T: 'static + Send + Sync, U: 'static + Send + Sync,

Create a node that provides a blocking map.

pub fn create_map_async<T, Task>( &mut self, f: impl FnMut(T) -> Task + 'static + Send + Sync, ) -> Node<T, Task::Output, ()>

where T: 'static + Send + Sync, Task: Future + 'static + Sendish, Task::Output: 'static + Send + Sync,

Create a node that provides an async map.

pub fn create_map<M, F: AsMap<M>>( &mut self, f: F, ) -> Node<RequestOfMap<M, F>, ResponseOfMap<M, F>, StreamsOfMap<M, F>>

where F::MapType: Provider, RequestOfMap<M, F>: 'static + Send + Sync, ResponseOfMap<M, F>: 'static + Send + Sync, StreamsOfMap<M, F>: StreamPack,

Create a map (either a blocking map or an async map) by providing a function that takes BlockingMap or AsyncMap as its only argument.

pub fn create_injection_node<Request, Response, Streams>( &mut self, ) -> Node<(Request, ServiceInstructions<Request, Response, Streams>), Response, Streams>

where Request: 'static + Send + Sync, Response: 'static + Send + Sync + Unpin, Streams: StreamPack,

Create a node that takes in a (request, service) at runtime and then passes the request into the service. All streams will be forwarded and the response of the service will be the node’s output.

This allows services to be injected into workflows as input, or for a service to be chosen during runtime.

pub fn connect<T: 'static + Send + Sync>( &mut self, output: Output<T>, input: InputSlot<T>, )

Connect the output of one into the input slot of another node.

pub fn create_buffer<T: 'static + Send + Sync>( &mut self, settings: BufferSettings, ) -> Buffer<T>

Create a Buffer which can be used to store and pull data within a scope. This is often used along with joining to synchronize multiple branches.

pub fn create_scope<Request, Response, Streams, Settings>( &mut self, build: impl FnOnce(Scope<Request, Response, Streams>, &mut Builder<'_, '_, '_>) -> Settings, ) -> Node<Request, Response, Streams>

where Request: 'static + Send + Sync, Response: 'static + Send + Sync, Streams: StreamPack, Settings: Into<ScopeSettings>,

Create an isolated scope within the workflow. This can be useful for racing multiple branches, creating an uninterruptible segment within your workflow, or being able to run the same multiple instances of the same sub-workflow in parallel without them interfering with each other.

A value can be sent into the scope by connecting an Output of a node in the parent scope to the InputSlot of the node which gets returned by this function. Each time a value is sent into the scope, it will run through the workflow of the scope with a unique session ID. Even if multiple values are sent in from the same session, they will each be assigned their own unique session ID while inside of this scope.

pub fn create_io_scope<Request, Response, Settings>( &mut self, build: impl FnOnce(Scope<Request, Response, ()>, &mut Builder<'_, '_, '_>) -> Settings, ) -> Node<Request, Response, ()>

where Request: 'static + Send + Sync, Response: 'static + Send + Sync, Settings: Into<ScopeSettings>,

Alternative to Self::create_scope for pure input/output scopes (i.e. there are no output streams). Using this signature should allow the compiler to infer all the generic arguments when there are no streams.

pub fn create_fork_clone<T>(&mut self) -> (InputSlot<T>, ForkCloneOutput<T>)

where T: Clone + 'static + Send + Sync,

Create an operation that clones its inputs and sends them off to any number of targets.

pub fn create_unzip<T>(&mut self) -> (InputSlot<T>, T::Unzipped)

where T: Unzippable + 'static + Send + Sync,

Create an operation that unzips its inputs and sends each element off to a different output.

pub fn create_fork_result<T, E>( &mut self, ) -> (InputSlot<Result<T, E>>, ForkResultOutput<T, E>)

where T: 'static + Send + Sync, E: 'static + Send + Sync,

Create an operation that creates a fork for a Result input. The value inside the Result will be unpacked and sent down a different branch depending on whether it was in the Ok or Err variant.

pub fn create_fork_option<T>( &mut self, ) -> (InputSlot<Option<T>>, ForkOptionOutput<T>)

where T: 'static + Send + Sync,

Create an operation that creates a fork for an Option input. The value inside the Option will be unpacked and sent down a different branch depending on whether it was in the Some or None variant.

For the None variant a unit () output will be sent, also called a trigger.

pub fn join<'b, B: Joinable>( &'b mut self, buffers: B, ) -> Chain<'w, 's, 'a, 'b, B::Item>

Alternative way of calling Joinable::join

pub fn try_join<'b, J: Joined>( &'b mut self, buffers: &BufferMap, ) -> Result<Chain<'w, 's, 'a, 'b, J>, IncompatibleLayout>

Try joining a map of buffers into a single value.

pub fn listen<'b, B: Accessible>( &'b mut self, buffers: B, ) -> Chain<'w, 's, 'a, 'b, B::Keys>

Alternative way of calling Accessible::listen.

pub fn try_listen<'b, Keys: Accessor>( &'b mut self, buffers: &BufferMap, ) -> Result<Chain<'w, 's, 'a, 'b, Keys>, IncompatibleLayout>

Try listening to a map of buffers.

pub fn create_buffer_access<T, B: Bufferable>( &mut self, buffers: B, ) -> Node<T, (T, BufferKeys<B>)>

where B::BufferType: Accessing, T: 'static + Send + Sync,

Create a node that combines its inputs with access to some buffers. You must specify one ore more buffers to access. FOr multiple buffers, combine then into a tuple or an Iterator. Tuples of buffers can be nested inside each other.

Other outputs can also be passed in as buffers. These outputs will be transformed into a buffer with default buffer settings.

pub fn try_create_buffer_access<T, Keys: Accessor>( &mut self, buffers: &BufferMap, ) -> Result<Node<T, (T, Keys)>, IncompatibleLayout>

where T: 'static + Send + Sync,

Try to create access to some buffers. Same as Self::create_buffer_access except it will return an error if the buffers in the BufferMap are not compatible with the keys that are being asked for.

pub fn create_collect<T, const N: usize>( &mut self, min: usize, max: Option<usize>, ) -> Node<T, SmallVec<[T; N]>>

where T: 'static + Send + Sync,

Collect incoming workflow threads into a container.

If max is specified, the collection will always be sent out once it reaches that maximum value.

If min is greater than 0 then the collection will not be sent out unless it is equal to or greater than that value. Note that this means the collect operation could force the workflow into cancelling if it cannot reach the minimum number of elements. A min of 0 means that if an upstream thread is disposed and the collect node is no longer reachable then it will fire off with an empty collection.

If the min limit is satisfied and there are no remaining workflow threads that can reach this collect operation, then the collection will be sent out with however many elements it happens to have collected.

pub fn create_collect_all<T, const N: usize>( &mut self, ) -> Node<T, SmallVec<[T; N]>>

where T: 'static + Send + Sync,

Collect all workflow threads that are moving towards this node.

pub fn create_collect_n<T, const N: usize>( &mut self, n: usize, ) -> Node<T, SmallVec<[T; N]>>

where T: 'static + Send + Sync,

Collect an exact number of threads that are moving towards this node.

pub fn create_split<T>(&mut self) -> (InputSlot<T>, SplitOutputs<T>)

where T: 'static + Send + Sync + Splittable,

Create a new split operation in the workflow. The InputSlot can take in values that you want to split, and SplitOutputs::build will let you build connections to the split value.

pub fn create_cancel<T>(&mut self) -> InputSlot<T>

where T: 'static + Send + Sync + ToString,

Create an input slot that will cancel the current scope when it gets triggered. This can be used on types that implement ToString.

If you need to cancel for a type that does not implement ToString then convert it to a trigger () and then connect it to Self::create_quiet_cancel.

pub fn create_quiet_cancel(&mut self) -> InputSlot<()>

Create an input slot that will cancel that current scope when it gets triggered.

If you want the cancellation message to include information about the input value that triggered it, use Self::create_cancel.

pub fn on_cleanup<B, Settings>( &mut self, from_buffers: B, build: impl FnOnce(Scope<BufferKeys<B>, (), ()>, &mut Builder<'_, '_, '_>) -> Settings, )

where B: Bufferable, B::BufferType: Accessing, Settings: Into<ScopeSettings>,

This method allows you to define a cleanup workflow that branches off of this scope that will activate during the scope’s cleanup phase. The input to the cleanup workflow will be a key to access to one or more buffers from the parent scope.

Each different cleanup workflow that you define using this function will be given its own unique session ID when it gets run. You can define any number of cleanup workflows.

The parent scope will only finish its cleanup phase after all cleanup workflows for the scope have finished, either by terminating or by being cancelled themselves.

Cleanup workflows that you define with this function will always be run no matter how the scope finished. If you want a cleanup workflow that only runs when the scope is cancelled, use Self::on_cancel. If you want a cleanup workflow that only runs when the scope terminates successfully, then use Self::on_terminate. For easier runtime flexibility you can also use Self::on_cleanup_if.

pub fn on_cancel<B, Settings>( &mut self, from_buffers: B, build: impl FnOnce(Scope<BufferKeys<B>, (), ()>, &mut Builder<'_, '_, '_>) -> Settings, )

where B: Bufferable, B::BufferType: Accessing, Settings: Into<ScopeSettings>,

Define a cleanup workflow that only gets run if the scope was cancelled.

When the scope gets dropped before it terminates (i.e. the parent scope finished while this scope was active, and this scope is interruptible) that also counts as cancelled.

A scope which is set to be uninterruptible will still experience a cancellation if its terminal node becomes unreachable.

If you want a cleanup workflow that only runs when the scope terminates successfully then use Self::on_terminate. If you want a cleanup workflow that always runs when the scope is finished, then use Self::on_cleanup.

pub fn on_terminate<B, Settings>( &mut self, from_buffers: B, build: impl FnOnce(Scope<BufferKeys<B>, (), ()>, &mut Builder<'_, '_, '_>) -> Settings, )

where B: Bufferable, B::BufferType: Accessing, Settings: Into<ScopeSettings>,

Define a cleanup workflow that only gets run if the scope was successfully terminated. That means an input reached its terminal node, and now the scope is cleaning up.

If you want a cleanup workflow that only runs when the scope is cancelled then use Self::on_cancel. If you want a cleanup workflow that always runs when then scope is finished, then use Self::on_cleanup.

pub fn on_cleanup_if<B, Settings>( &mut self, conditions: CleanupWorkflowConditions, from_buffers: B, build: impl FnOnce(Scope<BufferKeys<B>, (), ()>, &mut Builder<'_, '_, '_>) -> Settings, )

where B: Bufferable, B::BufferType: Accessing, Settings: Into<ScopeSettings>,

Define a sub-workflow that will be run when this workflow is being cleaned up if the conditions are met. A workflow enters the cleanup stage when its terminal node is reached or if it gets cancelled.

pub fn create_trim<T>( &mut self, branches: impl IntoIterator<Item = TrimBranch>, ) -> Node<T, T>

where T: 'static + Send + Sync,

Create a node that trims (cancels) other nodes in the workflow when it gets activated. The input into the node will be passed along as output after the trimming is confirmed to be completed.

pub fn create_gate<T, B>(&mut self, buffers: B) -> Node<GateRequest<T>, T>

where B: Bufferable, T: 'static + Send + Sync,

Create a gate node that can open and close the gates on one or more buffers. Feed a GateRequest into the node and all the associated buffers will be opened or closed based on the action inside the request.

The data inside the request will be passed along as output once the gate action is finished.

See Gate to understand what happens when a gate is opened or closed.

pub fn create_gate_action<T, B>( &mut self, action: Gate, buffers: B, ) -> Node<T, T>

where B: Bufferable, T: 'static + Send + Sync,

Create a gate node that always opens or always closes the gates on one or more buffers.

The data sent into the node will be passed back out as input, unchanged.

See Gate to understand what happens when a gate is opened or closed.

pub fn create_gate_open<B, T>(&mut self, buffers: B) -> Node<T, T>

where B: Bufferable, T: 'static + Send + Sync,

Create a gate node that always opens the gates on one or more buffers.

See Gate to understand what happens when a gate is opened or closed.

pub fn create_gate_close<T, B>(&mut self, buffers: B) -> Node<T, T>

where B: Bufferable, T: 'static + Send + Sync,

Create a gate node that always closes the gates on one or more buffers.

See Gate to understand what happens when a gate is opened or closed.

pub fn scope(&self) -> Entity

Get the scope that this builder is building for.

pub fn commands(&mut self) -> &mut Commands<'w, 's>

Borrow the commands for the builder

pub fn context(&self) -> BuilderScopeContext