message-io

message-io is an asynchronous network message library for building network applications following the actor model. The library offers an event-based API over an abstraction network transport layer.

This library can be used but it is still growing, so if you see any bug or strange behaviour, please put an issue! Of course, any contribution is welcome!

For who is this project?

• People who want to make an application that needs to communicate over tcp/udp protocols.
• People who want to make a multiplayer game (server and/or client).
• People who don't want to deal with concurrence or socket connection problems.
• People who want to push the effort in the messages among the apps, not in how to transport them.

Features

• Asynchronous: internal poll event with non-blocking sockets using mio.
• Multiplatform: see mio platform support.
• TCP, UDP (with multicast option), protocols.
• FIFO events with internal timed and priority events.
• Really easy API:
  • Abstraction from transport layer: Do not thinks about sockets, only thing about data messages.
  • Only two main entities: an extensible event-queue to manage all events. and a network manager to manage the connections, and send/receive data.
  • Forget concurrence problems: Manage thousands of active connections without any effort, "One thread to rule them all".
• High performance:
  • One thread for manage all internal connections over a OS poll.
  • Binary serialization.
  • Small runtime overhead over OS sockets.

Getting started

Add to your Cargo.toml

message-io = "0.4"

Documentation

• Basic concepts

• API documentation

• Examples:

  • Basic TCP client and server
  • Basic UDP client and server
  • Multicast
  • Distributed network with discovery server

Minimal TCP/UDP server

The following example is the simplest server that reads message from a client and respond to it. It is capable to manage several client connections and listen from 2 differents ports and interfaces.

use message_io::events::{EventQueue};
use message_io::network::{NetworkManager, NetEvent};

use serde::{Serialize, Deserialize};

#[derive(Deserialize)]
enum InputMessage {
    HelloServer(String),
    // Other input messages here
}

#[derive(Serialize)]
enum OutputMessage {
    HelloClient(String),
    // Other output messages here
}

enum Event {
    Network(NetEvent<InputMessage>),
    // Other user events here
}

fn main() {
    let mut event_queue = EventQueue::new();

    // Create NetworkManager, the callback will push the network event into the event queue
    let sender = event_queue.sender().clone();
    let mut network = NetworkManager::new(move |net_event| sender.send(Event::Network(net_event)));

    // Listen from TCP and UDP messages on ports 3005.
    let addr = "0.0.0.0:3005";
    network.listen_tcp(addr).unwrap();
    network.listen_udp(addr).unwrap();

    loop {
        match event_queue.receive() { // Read the next event or wait until have it.
            Event::Network(net_event) => match net_event {
                NetEvent::Message(endpoint, message) => match message {
                    InputMessage::HelloServer(msg) => {
                        println!("Received: {}", msg);
                        network.send(endpoint, OutputMessage::HelloClient(msg)).unwrap();
                    },
                    //Other input messages here
                },
                NetEvent::AddedEndpoint(_endpoint) => println!("TCP Client connected"),
                NetEvent::RemovedEndpoint(_endpoint) => println!("TCP Client disconnected"),
            },
            // Other events here
        }
    }
}

Basic concepts

The library has two main pieces:

• EventQueue: Is a generic and synchronized queue where all the system events are sent. The user must be read these events in its main thread in order to dispatch actions.

• NetworkManager: It is an abstraction layer of the transport protocols that works over non-blocking sockets. It allows to create/remove connections, send and receive messages (defined by the user).

To manage the connections the NetworkManager offers an Endpoint that is an unique identifier of the connection that can be used to remove, send or identify input messages.

The power comes when both pieces joins together, allowing to process all actions from one thread. To reach this, the user have to connect the NetworkManager to the EventQueue sending NetEvent produced by the first one.

Test yourself!

Clone the repository and test the basicexample that you can found in examples/basic:

Run the server:

cargo run --example basic server [tcp/udp]

In other terminals, run one or more clients:

cargo run --example basic client [tcp/udp]

(By default, if no protocol is specified, tcp is used)