Struct ump_ng::Client

pub struct Client<P, S, R, E>(/* private fields */);

Representation of a clonable client object.

Each instantiation of a Client object is itself an isolated client with regards to the server context. By cloning a client a new independent client is created. (“Independent” here meaning that it is still tied to the same server object, but the new client can be passed to a separate thread and can independently make calls to the server).

Implementations

impl<P, S, R, E> Client<P, S, R, E>

where P: 'static + Send, R: 'static + Send, E: 'static + Send,

pub fn post(&self, msg: P) -> Result<(), Error<E>>

Transmit a uni-directional message to the server end-point.

pub fn req(&self, out: S) -> Result<R, Error<E>>

Send a message to the server, wait for a reply, and return the reply.

A complete round-trip (the message is delivered to the server, and the server sends a reply) must complete before this function returns success.

This method is currently reentrant: It is safe to use share a single Client among multiple threads. This may change in the future; it’s recommended to not rely on this. The recommended way to send messages to a server from multiple threads is to clone the Client and assign one separate Client to each thread.

Return

On success the function will return Ok(msg).

If the linked server object has been released, or is released while the message is in the server’s queue, Err(Error:ServerDisappeared) will be returned.

If the server never replied to the message and the reply context was dropped Err(Error::NoReply) will be returned.

If an application specific error occurs it will be returned as a Err(Error::App(E)), where E is the error type used when creating the channel.

pub fn req_async(&self, out: S) -> Result<WaitReply<R, E>, Error<E>>

Issue a request, immediately returning a context that is used to wait for the server’s reply.

The _async naming is slightly misleading – this method isn’t an async in a language/Future sense, but rather it doesn’t block and wait for a reply before returning. Instead it returns a WaitReply object that is used to wait for the reply.

This can be useful (in place of req() or areq() methods) if the caller knows that the server will take some time to respond to the request and the caller has other tasks it can perform in the meantime.

use std::thread;

use ump_ng::{channel, MsgType};

let (server, client) = channel::<String, String, String, ()>();

let server_thread = thread::spawn(move || {
  // Wait for data to arrive from a client
  println!("Server waiting for message ..");
  let MsgType::Request(data, mut rctx) = server.wait().unwrap() else {
    panic!("Unexpected message type");
  };

  println!("Server received: '{}'", data);

  // Long processing of data from client

  // Reply to client
  let reply = format!("Hello, {}!", data);
  println!("Server replying '{}'", reply);
  rctx.reply(reply);

  println!("Server done");
});

let msg = String::from("Client");
println!("Client sending '{}'", msg);
let wrctx = client.req_async(msg).unwrap();

// .. perform some operation while server is processing the request ..

let reply = wrctx.wait().unwrap();
println!("Client received reply '{}'", reply);
println!("Client done");

server_thread.join().unwrap();

pub async fn areq(&self, out: S) -> Result<R, Error<E>>

Same as Client::req() but for use in async contexts.

pub fn weak(&self) -> WeakClient<P, S, R, E>

Create a weak Client reference.

Trait Implementations

impl<P, S, R, E> Clone for Client<P, S, R, E>

fn clone(&self) -> Self

Clone a client.

When a client is cloned the new object will be linked to the same server, but in all other respects the clone is a completely independent client.

This means that a cloned client can be passed to a new thread/task and make new independent calls to the server without any risk of collision between clone and the original client object.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.