Network engine refactorization (lemunozm#24)

* Unified adapter threads. Generalize architecture.

* Fixed decode function. Minor change

* Fixed tests

* Added logger to test and check the timeouts

* cargo fmt

* Minnor refactorization.

* Adjust some net constants

* Added adapter trait

* Fixed cargo clippy

* Compiled in rust stable!

* Minnor change. Documented adapter.

* Updated readme: add adapters.

Author: lemunozm

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Release 0.6.1
+- Internal improvements in order to use one thread for all adapters.
+- Clean architecture to implement new adapters easier.
+
 ## Release 0.6.0
 - Added concurrent writing and reading from socket/streams in UDP and TCP protocols.
 - Removed UDP enconding (improved speed)

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "message-io"
-version = "0.6.0"
+version = "0.6.1"
 authors = ["lemunozm <lemunozm@gmail.com>"]
 edition = "2018"
 readme = "README.md"
@@ -22,6 +22,7 @@ crossbeam = "0.8"
 log = "0.4"
 net2 = "0.2.34"
 num_enum = "0.5.1"
+strum = { version = "0.20", features = ["derive"] }
 
 #![cfg_attr(test, feature(proc_macro))]
 #[cfg(test)]
@@ -30,6 +31,7 @@ lazy_static = "1.4.0"
 [dev-dependencies]
 criterion = "0.3"
 serde-big-array = "0.3"
+simple_logger = "1.11.0"
 
 [[bench]]
 name = "performance"

Cargo.toml

@@ -10,6 +10,11 @@
   <img src="https://docs.google.com/drawings/d/e/2PACX-1vSPmycMsWoQq60MPEODcakFQVPkDwVy98AnduTswFNPGBB5dpbIsSCHHBhS2iEuSUtbVaYQb7zgfgjO/pub?w=653&h=305" width="653"/>
 </p>
 
+Also, it can be understanding as a **generic manager network**.
+This means that you can implement your own protocol following some rules
+and `message-io` will manage the tedious asynchrony and thread management for you.
+See more [here](#custom-adapter).
+
 **Any contribution is welcome!**
 
 ## Who is this project for?
@@ -162,12 +167,16 @@ In other terminals, run one or more clients:
 cargo run --example tcp client <name>
 ```
 
-## Not found the transport protocol you need? Add it easily!
+## Do you need a transport protocol that `message-io` doesn't have? Add it! <span id="custom-adapter"><span>
+
+If the protocol can be built in top on [`mio`](https://github.com/tokio-rs/mio#platforms)
+(most of the existing protocol libraries can), then you can add it to `message-io` **really easy**:
+
+1. Add your *adapter* file in `src/adapters/<my-transport-protocol>.rs` that implements the
+  traits that you can found in [`src/adapter.rs`](src/adapter.rs).
+
+1. Add a new field in the `Transport` enum found in [`src/network.rs`] to register your new adapter.
 
-- Add your *adapter* file in `src/adapters/<my-transport-protocol>.rs`
-- Modify the `src/network.rs` in two ways:
-  - Add a new entry of the `Transport` enum with your transport name.
-  - Fill the main functions with your transport calls following the existing pattern.
+That's all! You can use your new transport in the `message-io` API like any other.
 
-Of course, any contribution of any kind: ideas, fixing bugs, adding tests, examples...
-is really appreciated.
+Oops, one step more, you can make a *Pull request* for everyone to use it :)

README.md

@@ -0,0 +1,80 @@
+use crate::endpoint::{Endpoint};
+use crate::resource_id::{ResourceId};
+use crate::poll::{PollRegister};
+use crate::util::{SendingStatus};
+
+use std::net::{SocketAddr};
+use std::io::{self};
+
+/// Struct used to pack the events generated by the adapter.
+/// The upper layer will traduce this event into a [crate::network::NetEvent]
+/// that the user can manage.
+pub enum AdapterEvent<'a> {
+    Added,
+    Data(&'a [u8]),
+    Removed,
+}
+
+/// High level trait to represent an adapter for a transport protocol.
+/// The adapter is used to pack a [`Controller`] and [`Adapter`].
+/// Two traits to describes how an adapter behaves.
+pub trait Adapter<C>
+where C: FnMut(Endpoint, AdapterEvent<'_>)
+{
+    type Controller: Controller + Send;
+    type Processor: Processor<C> + Send;
+
+    /// Creates a [`Controller`] and [`Processor`] that represents the adapter.
+    /// The **implementator** must create their [`Controller`] and [`Processor`] here.
+    fn split(self, poll_register: PollRegister) -> (Self::Controller, Self::Processor);
+}
+
+/// It is in change to perform direct actions from the user.
+pub trait Controller {
+    /// The user performs a connection request to an specific address.
+    /// The **implementator** is in change of creating the corresponding instance in order
+    /// to manage it later.
+    fn connect(&mut self, addr: SocketAddr) -> io::Result<Endpoint>;
+
+    /// The user performs a listening request from an specific address.
+    /// The **implementator** is in change of creating the corresponding instance in order
+    /// to manage it later.
+    fn listen(&mut self, addr: SocketAddr) -> io::Result<(ResourceId, SocketAddr)>;
+
+    /// The user performs a remove action in order to remove a resource generated by
+    /// [connect()] and [listen()] functions.
+    /// The **implementator** must remove the resource here.
+    fn remove(&mut self, id: ResourceId) -> Option<()>;
+
+    /// The user wants to get the local address of some resource (listener or remote).
+    /// The **implementator** must return that address or None if the resource is not found.
+    /// Note: The *peer* address can be retreived from the Endpoint that the user already has.
+    fn local_addr(&self, id: ResourceId) -> Option<SocketAddr>;
+
+    /// Sends a raw message by the specific endpoint.
+    /// The **implementator** is in charge to send the `data` using the instance represented by
+    /// `endpoint.resource_id()`.
+    fn send(&mut self, endpoint: Endpoint, data: &[u8]) -> SendingStatus;
+}
+
+/// It is in change to perform eventual actions comming from the internal network engine.
+/// The `event_callback` is the action that will be performed when an [AdapterEvent] is
+/// generated for some `Endpoint`.
+pub trait Processor<C>
+where C: FnMut(Endpoint, AdapterEvent<'_>)
+{
+    /// Called when a listener received an event.
+    /// It means that an endpoint has try to connect and the connection should accept.
+    /// The `id` represents the listener that have generated the event.
+    /// The **implementator** is in charge of retrive the instance represented by this `id`
+    /// to accept that connection.
+    fn process_listener(&mut self, id: ResourceId, event_callback: &mut C);
+
+    /// Called when a remote endpoint received an event.
+    /// It means that the endpoint has available data to read,
+    /// or there is some connection related issue, as a disconnection.
+    /// The `id` represents the remote entity that has generated the event.
+    /// The **implementator** is in charge of retrive the instance represented by this `id`
+    /// and process the event.
+    fn process_remote(&mut self, id: ResourceId, event_callback: &mut C);
+}