[−][src]Crate lifeline
Lifeline is a dependency injection for asynchronous message-based applications. Lifeline provides:
- The Bus, which constructs & distributes channel Senders/Receivers, and Resources.
- The Carrier, which drives messages between Busses. Carriers are critical when building large applications.
- The Service, which takes channels from the bus, and drives messages along the channels.
- The Task, an async future which returns a lifeline when spawned. When the lifeline is dropped, the future is immedately cancelled.
- The Resource, a struct which can be stored in the bus, and taken (or cloned) when services spawn.
For a quick overview, see the hello.rs example.
Quickstart
Lifeline uses tokio
as it's default runtime. Tokio provides a rich set of async channels.
lifeline = "0.3"
Lifeline also supports the async-std runtime, and it's mpsc
channel implementation:
lifeline = { version = "0.3", features = ["dyn-bus", "async-std-executor", "async-std-channels"] }
The Bus
The Bus carries channels and resources, and allows you to write loosely coupled Service implementations which communicate over messages.
Channels can be taken from the bus. If the channel endpoint is clonable, it will remain available for other services.
But if the channel is !Clone
, future calls will return an Err. The Rx/Tx type parameters are type-safe,
and will produce a compile error if you attempt to take a channel for an message type which the bus does not carry.
Lifeline provides a lifeline_bus! macro which stores channels and resources in Box<dyn>
slots:
use lifeline::lifeline_bus; lifeline_bus!(pub struct MainBus);
The Carrier
Carriers provide a way to move messages between busses. Carriers can translate, ignore, or collect information, providing each bus with the messages that it needs.
Large applications have a tree of Busses. This is good, it breaks your app into small chunks.
- Main
| ConnectionListenerBus
| | ConnectionBus
| DomainSpecificBus
| | ...
Carriers allow each bus to define messages that minimally represent the information it's services need to function.
Carriers centralize the communication between busses, making large applications easier to reason about.
The Service
The Service takes channel endpoints from the bus, and spawns tasks.
Taking channel endpoints and resources is fallible. Depending on the channel type, the endpoint may not be clonable.
Lifeline clones endpoints when it can (e.g. for mpsc::Sender
, broadcast::*
, and watch::Receiver
). Other endpoints are taken, removed, and future calls will return an Err.
Service::spawn takes channels from the bus synchronously, which makes errors occur predictably and early. If you get an Err on an mpsc::Receiver, change it's binding in the bus to broadcast.
The Task
The Task executes an Future, and returns a Lifeline when spawned. When the lifeline is dropped, the future is immediately cancelled.
Task trait is implemented for all types - you can import it and use Self::task
in any type. In lifeline, it's
most commonly used in Service implementations.
The Resource
Resources can be stored on the bus. This is very useful for configuration (e.g MainConfig), or connections (e.g. a TcpStream).
Resources implement the Storage trait, which is easy with the impl_storage_clone! and impl_storage_take! macros.
Modules
dyn_bus | The DynBus implementation used by |
error | All the lifeline error types. |
prelude | Prelude, including all the traits and types required for typical lifeline usage. |
request | A request/response helper type, which can be sent over messages. |
subscription | A subscription utility, which can maintain a subscription state, and generate unique identifiers for each new subscription. |
test | Helpers which assist in testing applications based on lifeline. |
Macros
assert_completes | Asserts that the expression completes within a given number of milliseconds. |
assert_times_out | Asserts that the expression does not complete within a given number of milliseconds. |
impl_channel_clone | Specifies that this channel endpoint (Sender or Receiver) is clonable. Provides a generic type T with the bounds required for the implementation. |
impl_channel_take | Specifies that this channel endpoint (Sender or Receiver) is taken. Provides a generic type T with the bounds required for the implementation. |
impl_storage_clone | Specifies that this resource is cloned. |
impl_storage_take | Specifies that this resource is taken, and is !Clone. |
lifeline_bus | Defines a lifeline bus: it's struct, |
Structs
Lifeline | A lifeline value, associated with a future spawned via the |
LifelineReceiver | A wrapper which provides a stable Receiver implementation, returned by bus.rx::<Msg>(). Can be unwrapped with into_inner() |
LifelineSender | A wrapper which provides a stable Sender implementation, returned by bus.tx::<Msg>(). Can be unwrapped with into_inner() |
Enums
Link | Represents the Sender, Receiver, or Both. Used in error types. |
Traits
Bus | Stores and distributes channel endpoints (Senders and Receivers), as well as Resource values. |
CarryFrom | Carries messages between two bus instances. A variant of the Service. |
CarryInto | The receprocial of the |
Channel | A channel's (Sender, Receiver) pair. Defines how the bus constructs and retrieves the values. |
DefaultCarrier | Constructs two bus types, and spawns the carrier between them. Returns both busses, and the carrier's lifeline. |
DefaultService | Constructs the bus, spawns the service, and returns both. |
Message | Attaches a channel to the Bus, carrying Self as a message. |
Receiver | The receiver half of an asynchronous channel, which may be bounded/unbounded, mpsc/broadcast/oneshot, etc. |
Resource | Attaches a resource to the Bus. This resource can accessed from the bus using bus.resource::<Self>(). |
Sender | The sender half of an asynchronous channel, which may be bounded/unbounded, mpsc/broadcast/oneshot, etc. |
Service | Takes channels from the Bus, and spawns a tree of tasks. Returns one or more Lifeline values. |
Storage | Defines a resource (or channel endpoint) which can be stored on the bus, and how it is taken or cloned. |
Task | Provides the Self::task and Self::try_task associated methods for all types. |