Crate ump

Micro Message Pass (ump) is a library for passing messages between thread/tasks. It has some similarities with the common mpsc channel libraries, but with the most notable difference that each time a client sends a message the server must send back a reply.

The primary purpose of ump is to create simple RPC like designs, but between threads/tasks within a process rather than between processes over networks.

High-level usage overview

An application calls channel to create a linked pair of a Server and a Client.

The server calls Server::wait()/Server::async_wait(), which blocks and waits for an incoming message from a client.

A client, in a separate thread or task, calls Client::send()/Client::asend() to send a message to the server.

The server’s wait call returns two objects: The message sent by the client, and a ReplyContext.

After processing its application-defined message, the server must call the ReplyContext::reply() on the returned reply context object to return a reply message to the client.

Typically the server calls wait again to wait for next message from a client.

The client receives the reply from the server and processes it.

Example

use std::thread;

use ump::channel;

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

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

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

   // Process 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 reply = client.send(String::from(msg)).unwrap();
 println!("Client received reply '{}'", reply);
 println!("Client done");

 server_thread.join().unwrap();
}

In practice the send/reply types will probably be enums used to indicate command/return type with associated data. The third type argument to channel is an error type that can be used to explicitly pass errors back to the sender.

Semantics

There are some potentially useful semantic quirks that can be good to know about, but some of them should be used with caution. This section will describe some semantics that you can rely on, and others that you should be careful about relying on.

Stable invariants

These are behaviors which should not change in future versions.

• The reply contexts are independent of the Server context. This has some useful implications for server threads that spawn separate threads to process messages and return replies: The server can safely terminate while there are clients waiting for replies (implied: the server can safely terminate while there are reply contexts in-flight).
• A cloned client is paired with the same server as its origin, but in all other respects the clone and its origin are independent of each other.
• A client can be moved to a new thread.
• Any permutation of sync/async server/clients can be combined. async code must use the async method variants when available.

Unstable invariants

These are invariants you can trust will work in the current version, but they exist merely as a side-effect of the current implementation. Avoid relying on these if possible.

• A single client can be used from two different threads. If a Client object in placed in an Arc, is cloned and passed to another thread/task then both the clone and the original can be used simultaneously. In the future this may not be allowed. It is recommended that a new clone of the client be created instead.

Structs

Client

Representation of a clonable client object.

ReplyContext

Public-facing sender part of the ReplyContext object.

Server

Representation of a server object.

Enums

Error

Module-specific error codes.

Functions

channel

Create a pair of linked Server and Client objects.