2 releases

0.1.3 Nov 13, 2020
0.1.2 Oct 29, 2020

#2154 in Asynchronous

MIT/Apache

220KB
3K SLoC

D3 -- A Framework for Server Development

Build Status Test Status License Cargo Documentation Rust 1.47+

This crate provides a framework for server development. It is especially well suited for those cases where the server employs a pipeline architecture.

There are two core concepts, the machine, and the instruction set. Combined with a channel sender and receiver, you have all of the parts necessary for building a server. Strictly speaking, the d3 framework can be used for non-server projects, anywhere where you have concurrent, cooperative object instances.

The Instruction Set

The Instruction Set starts with any kind of enum. It becomes an instruction set when MachineImpl is derived.

The Machine

The machine is an instance of any struct, implementing one or more instruction sets and connected to the collective. Machines, asynchronously, communicate with each other via the instruction sets they implement.

Example

This example shows how easy it is to create an instruction set, create a machine and send an instruction to that machine.

// A trivial instruction set
#[derive(Debug, MachineImpl)]
enum StateTable { Init, Start, Stop }

// A trivial Alice
pub struct Alice {}

// Implement the Machine trait for Alice
impl Machine<StateTable> for Alice {
     fn receive(&self, cmd: StateTable) {
     }
}

// create the Machine from Alice, getting back a machine and Sender<StateTable>.
let (alice, sender) = executor::connect(Alice{});

// send a command to Alice
// Alice's receive method will be invoked, with cmd of StateTable::Init.
sender.send(StateTable::Init).expect("send failed");

Crates

The main d3 crate just re-exports tools from smaller subcrates:

d3-derive

  • MachineImpl, a derive macro for tranforming an enum into a d3 instruction set.

d3-core

  • machine_impl, a packaged namespace to be used alongside #[derive(MachineImpl)].
  • executor, a packaged namespace to facilitate interacting with the collective.

d3-components

  • components, a packaged namespace for managing machines. It is modeled upon a component, coordinator, connector model.
  • network, a TCP abstraction consumable by machines. It wraps Mio.

Examples

A numer of aexamples are available. Fork the d3 repo and cargo run -p test-server --release for an example of a server with services.

Services

Applications

Usage

Add this to your Cargo.toml:

[dependencies]
d3 = "0.1.3"

Compatibility

d3 supports stable Rust releases going back at least six months, and every time the minimum supported Rust version is increased, a new minor version is released. Currently, the minimum supported Rust version is 1.47.

Contributing

d3 welcomes contribution from everyone in the form of suggestions, bug reports, pull requests, and feedback. 💛

If you need ideas for contribution, there are several ways to get started:

Learning Resources

If you'd like to learn more read our wiki

Conduct

The d3 project adheres to the Rust Code of Conduct. This describes the minimum behavior expected from all contributors.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~6–14MB
~179K SLoC