Struct ockam::pipe2::PipeBuilder

pub struct PipeBuilder { /* private fields */ }

A builder structure for pipes

A pipe is a unidirectional message sending abstraction, which optionally provides ordering and delivery guarantees. The two basic pipe initialisation modes are Fixed, connecting to a specific peer route, and Dynamic, connecting to a handshake worker which then creates a remote peer dynamically.

Static example

The easiest way to get started with pipes is with a static route. This requires a running PipeReceiver worker on a remote system.

Code on machine A:

let result = PipeBuilder::fixed()
    .connect(vec![tcp_connection, my_pipe])
    .build(ctx)
    .await?;

ctx.send(
    vec![result.addr(), "app".into()], // Send a message through the pipe to "app"
    String::from("Hello you on the other end of this pipe!"),
)
.await?;

Code on machine B:

let receive = PipeBuilder::fixed()
    .receive(my_pipe)
    .build(ctx)
    .await?;

let msg = ctx.receive::<String>().await?;
println!("Message from pipe: {}", msg);

Implementations

impl PipeBuilder

pub fn fixed() -> Self

Construct a fixed pipe to a specific well-known peer

pub fn dynamic() -> Self

Construct a pipe using dynamic initialisation handshakes

pub fn connect<R: Into<Route>>(self, peer: R) -> Self

Set a connection peer, creating an outgoing pipe

• In fixed mode this attempts to connect directly to a receiver at the given peer route.

• In dynamic mode this initiates a handshake with the given peer. This handshake then resolves to the final receiver

pub fn receive<A: Into<Address>>(self, addr: A) -> Self

Set a receiving address, creating a receiving pipe

• In fixed mode this creates a pipe receiver which waits for incoming messages from a sender.

• In dynamic mode this spawns a handshake listener, which will create pipe receivers dynamically for any incoming initialisation request

pub fn enforce_ordering(self) -> Self

Set this pipe to enforce the ordering of incoming messages

pub fn delivery_ack(self) -> Self

Enable the delivery guarantee behaviour on this pipe

Additional behaviours can be added to compose a custom pipe worker.

pub async fn build(self, ctx: &mut Context) -> Result<BuilderResult>

Consume this builder and construct a set of pipes