Crate ump_server 

ump-server is an abstraction on top of ump that is used to hide boilerplate code used to implement intra-process message passing servers.

Dispatch loop

The core functionality of ump-server is a dispatch loop, whose role it is to pull messages off the message queue and pass them to the application-supplied message handler.

There are two different ways to run the dispatcher loop: On a non-async thread or as an async task. The former is launched using thread::spawn() and the latter task::spawn() (only available using the tokio feature).

The spawn() functions return a tuple containing a Client (that can be used to send pass messages to the server) and a JoinHandle that can be used to wait for the dispatch loop thread/task to terminate (and retreive its return value).

The returned JoinHandle will, once joined, return an Option<RV>. If this is None the server was terminated because all the Client endpoints were dropped. If this is Some(RV) the server was terminated because a callback requested its termination by returning ControlFlow::Break(RV).

There are two ways to terminate the dispatch loop:

• The message processing handler returns ControlFlow::Break(RV) (rather than ControlFlow::Continue(())). This would cause the thread/task to return Some(RV).
• The message queue is empty and all the associated Clients have been released. This would cause the thread to return None.

Application message handlers

Message handlers are implemented using the thread::Handler trait (for the threaded dispatch loop) and task::Handler (for the async dispatch loop).

There are cases where the handler needs to store a clone of the client end-point of the message passing channel used to issue requests to the server (so that message handlers can issue new requests). In order to facilitate this, the application must pass a Handler-construction closure to spawn(). The closure will be called after the message passing channel has been created so it can be passed a reference to the client end-point.

If the dispatch loop should terminate once all the application’s client end-points have been dropped, then the handler can store a WeakClient instead (as storing a cloned Client object will preventing the dispatch loop from terminating due to all clients being lost). The examples in the task and thread modules illustrate how to do this.

Generics

When a new handler is created, it needs to define the generic type parameters:

• S - sent from the client to the server handler when making requests.
• R - replies sent back to the client from the server handler using. ReplyContext::reply().
• E - errors returned from server handler to requestor through ReplyContext::fail() (and also returned by the server handler construction closure).
• RV - return type the server handler can use to pass termination data back to the dispatch loop creator once it terminates.

Re-exports

pub use thread::Handler as ThreadedHandler;

pub use thread::spawn as spawn_thread;

pub use task::Handler as AsyncHandler;tokio

pub use task::spawn as spawn_task;tokio

pub use ump;

Modules

tasktokio

ump server running in an async task.

thread

ump server running on a thread.

Structs

Client

Representation of a clonable client object that can issue requests to Server objects.

ReplyContext

Object used to respond to requests that have been received by a Server.

WeakClient

A weak client reference that can be upgraded to a Client as long as other Client objects till exist.

Enums

Error

Module-specific error codes.

Functions

channel

Create a pair of linked Server and Client objects.

Attribute Macros

async_traittokio