2 releases
0.1.3 | Nov 13, 2020 |
---|---|
0.1.2 | Oct 29, 2020 |
#2154 in Asynchronous
220KB
3K
SLoC
D3 -- A Framework for Server Development
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
echo service
, an example of a TCP echo serviceudp echo service
, an example of a UDP echo servicechat service
, an example of a TCP chat servicealice service
, an example of an HTTP service with form manipulationmonitor service
, an example of how to monitor the core
Applications
test server
, an example of a configurable server providing servicesConway's Game of Life
, an example of a game with a UI and interacting machines
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:
- Found a bug or have a feature request? Submit an issue!
- Issues and PRs labeled with feedback wanted
- Issues labeled with good first issue are relatively easy starter issues.
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
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
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