Salticidae: a Minimal C++ asynchronous network library. ======================================================= .. image:: https://img.shields.io/badge/License-MIT-yellow.svg :target: https://opensource.org/licenses/MIT Features -------- - Simplicity. The library is self-contained, small in code base, and only relies on libevent and libcrypo (OpenSSL, for SHA256 purpose). - Clarity. With moderate use of C++ template and new features, the vast majority of the code is self-documenting. - Layered design. You can use network abstraction from the lowest socket connection level to the highest P2P network level. - Performance. The implementation strives to incur very little overhead in processing network I/O, and avoid unnecessary memory copies thanks to the move semantics. - Utilities. The library also provides with some useful gadgets, such as command-line parser, libevent abstraction, etc. Functionalities --------------- - ``ConnPool``: byte level connection pool implementation, ``ConnPool::Conn`` (or ``ConnPool::conn_t``) objects represent connections to which one can send/receive a stream of binary data asynchronously. - ``MsgNetwork``: message level network pool implementation, ``MsgNetwork::Conn`` (or ``MsgNetwork::cont_t``) objects represent channels to which one can send/receive predefined messages asynchronously. Message handler functions are registered by ``reg_handler()`` and invoked upon receiving a new message. ``OpcodeType`` is the type used for identifying message types. A valid message class must have: - a static member ``opcode`` typed ``OpcodeType`` as the message type identifier - a member ``serialized`` typed ``DataStream`` which contains the serialized data of the message. - a constructor ``MsgType(DataStream &&)`` that parse the message from stream. Based on ``MsgNetwork``, salticidae provides the following higher level abstractions: - ``PeerNetwork``: simple P2P network pool implementation. It will ensure exactly one underlying bi-directional connection is established per added peer, and retry the connection when it is broken. Ping-pong messages are utilized to test the connectivity periodically. - ``ClientNetwork``: simple client-server network pool implementation. A server who initially calls ``listen()`` will accept the incoming client messages, while a client simply calls ``connect()`` to connect to a known server. Dependencies ------------ - CMake >= 3.9 - C++14 - libevent - libcrypto Example (MsgNetwork layer) -------------------------- .. code-block:: cpp #include #include #include #include "salticidae/msg.h" #include "salticidae/event.h" #include "salticidae/network.h" #include "salticidae/stream.h" using salticidae::NetAddr; using salticidae::DataStream; using salticidae::MsgNetwork; using salticidae::htole; using salticidae::letoh; using std::placeholders::_1; using std::placeholders::_2; using opcode_t = uint8_t; /** Hello Message. */ struct MsgHello { static const opcode_t opcode = 0x0; DataStream serialized; std::string name; std::string text; /** Defines how to serialize the msg. */ MsgHello(const std::string &name, const std::string &text) { serialized << htole((uint32_t)name.length()); serialized << name << text; } /** Defines how to parse the msg. */ MsgHello(DataStream &&s) { uint32_t len; s >> len; len = letoh(len); name = std::string((const char *)s.get_data_inplace(len), len); len = s.size(); text = std::string((const char *)s.get_data_inplace(len), len); } }; /** Acknowledgement Message. */ struct MsgAck { static const opcode_t opcode = 0x1; DataStream serialized; MsgAck() {} MsgAck(DataStream &&s) {} }; const opcode_t MsgHello::opcode; const opcode_t MsgAck::opcode; using MsgNetworkByteOp = MsgNetwork; struct MyNet: public MsgNetworkByteOp { const std::string name; const NetAddr peer; MyNet(const salticidae::EventContext &ec, const std::string name, const NetAddr &peer): MsgNetwork(ec, 10, 1.0, 4096), name(name), peer(peer) { /* message handler could be a bound method */ reg_handler(salticidae::handler_bind( &MyNet::on_receive_hello, this, _1, _2)); } struct Conn: public MsgNetworkByteOp::Conn { MyNet *get_net() { return static_cast(get_pool()); } salticidae::RcObj self() { return salticidae::static_pointer_cast( MsgNetworkByteOp::Conn::self()); } void on_setup() override { auto net = get_net(); if (get_mode() == ACTIVE) { printf("[%s] Connected, sending hello.\n", net->name.c_str()); /* send the first message through this connection */ net->send_msg(MsgHello(net->name, "Hello there!"), self()); } else printf("[%s] Passively connected, waiting for greetings.\n", net->name.c_str()); } void on_teardown() override { auto net = get_net(); printf("[%s] Disconnected, retrying.\n", net->name.c_str()); /* try to reconnect to the same address */ net->connect(get_addr()); } }; using conn_t = salticidae::RcObj; salticidae::ConnPool::Conn *create_conn() override { return new Conn(); } void on_receive_hello(MsgHello &&msg, conn_t conn) { printf("[%s] %s says %s\n", name.c_str(), msg.name.c_str(), msg.text.c_str()); /* send acknowledgement */ send_msg(MsgAck(), conn); } }; void on_receive_ack(MsgAck &&msg, MyNet::conn_t conn) { auto net = conn->get_net(); printf("[%s] the peer knows\n", net->name.c_str()); } salticidae::EventContext ec; NetAddr alice_addr("127.0.0.1:1234"); NetAddr bob_addr("127.0.0.1:1235"); int main() { /* test two nodes */ MyNet alice(ec, "Alice", bob_addr); MyNet bob(ec, "Bob", alice_addr); /* message handler could be a normal function */ alice.reg_handler(on_receive_ack); bob.reg_handler(on_receive_ack); alice.listen(alice_addr); bob.listen(bob_addr); /* first attempt */ alice.connect(bob_addr); bob.connect(alice_addr); ec.dispatch(); return 0; }