ump_server/

lib.rs

//! _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 [`Client`]s 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.

#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(feature = "watchdog")]
mod wdog;

#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub mod task;

pub mod thread;

pub use ump::{self, Client, Error, ReplyContext, WeakClient, channel};

pub use thread::{Handler as ThreadedHandler, spawn as spawn_thread};

#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub use task::{Handler as AsyncHandler, spawn as spawn_task};

#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub use async_trait::async_trait;

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :