add example and readme

7 files changed, 361 insertions, 26 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..300047d
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,171 @@
+Salticidae: a Minimal C++ asynchronous network library.
+=======================================================
+
+.. image:: https://img.shields.io/github/license/Determinant/salticidae.svg
+   :target: https://github.com/Determinant/salticidae
+
+
+Feaures
+-------
+
+- 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-documented.
+
+- 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 in processing
+  network I/O, and avoid unnecessary memory copies thanks to the move semantics.
+
+- Utilities. The libray also provies with some useful gadgets, such as command
+  line parser, libevent abstraction, etc.
+
+Dependencies
+------------
+
+- CMake >= 3.9
+- C++14
+- libevent
+- libcrypto
+
+Example
+-------
+
+.. code-block:: cpp
+
+   #include <cstdio>
+   #include <string>
+   
+   #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 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) {}
+   };
+   
+   using MsgNetworkByteOp = MsgNetwork<opcode_t>;
+   
+   struct MyNet: public MsgNetworkByteOp {
+       const std::string name;
+       const NetAddr peer;
+   
+       MyNet(const salticidae::EventContext &ec,
+               const std::string name,
+               const NetAddr &peer):
+           MsgNetwork<opcode_t>(ec, 10, 1.0, 4096),
+           name(name),
+           peer(peer) {}
+   
+       struct Conn: public MsgNetworkByteOp::Conn {
+           MyNet *get_net() { return static_cast<MyNet *>(get_pool()); }
+           salticidae::RcObj<Conn> self() {
+               return salticidae::static_pointer_cast<Conn>(
+                   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<Conn>;
+   
+       salticidae::ConnPool::Conn *create_conn() override {
+           return new Conn();
+       }
+   };
+   
+   
+   void on_receive_hello(MsgHello &&msg, MyNet::conn_t conn) {
+       auto net = conn->get_net();
+       printf("[%s] %s says %s\n",
+               net->name.c_str(),
+               msg.name.c_str(), msg.text.c_str());
+       /* send acknowledgement */
+       net->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);
+   
+       /* register the message handler */
+       alice.reg_handler(on_receive_hello);
+       alice.reg_handler(on_receive_ack);
+       bob.reg_handler(on_receive_hello);
+       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;
+   }
diff --git a/include/salticidae/conn.h b/include/salticidae/conn.h
index 3742975..aa414e8 100644
--- a/include/salticidae/conn.h
+++ b/include/salticidae/conn.h
@@ -177,7 +177,7 @@ class ConnPool {
         void conn_server(evutil_socket_t, short);
 
         public:
-        Conn(): self_ref(this), ready_send(false) {}
+        Conn(): ready_send(false) {}
         Conn(const Conn &) = delete;
         Conn(Conn &&other) = delete;
     
@@ -244,19 +244,19 @@ class ConnPool {
     conn_t add_conn(conn_t conn);
 
     protected:
-    EventContext eb;
+    EventContext ec;
     /** Should be implemented by derived class to return a new Conn object. */
-    virtual conn_t create_conn() = 0;
+    virtual Conn *create_conn() = 0;
 
     public:
-    ConnPool(const EventContext &eb,
+    ConnPool(const EventContext &ec,
             int max_listen_backlog = 10,
             double conn_server_timeout = 2,
             size_t seg_buff_size = 4096):
         max_listen_backlog(max_listen_backlog),
         conn_server_timeout(conn_server_timeout),
         seg_buff_size(seg_buff_size),
-        eb(eb) {}
+        ec(ec) {}
 
     ~ConnPool() {
         for (auto it: pool)
diff --git a/include/salticidae/network.h b/include/salticidae/network.h
index 0d754d6..6556d22 100644
--- a/include/salticidae/network.h
+++ b/include/salticidae/network.h
@@ -134,14 +134,14 @@ class MsgNetwork: public ConnPool {
     mutable msg_stat_by_opcode_t recv_by_opcode;
 #endif
 
-    ConnPool::conn_t create_conn() override { return (new Conn())->self(); }
+    ConnPool::Conn *create_conn() override { return new Conn(); }
 
     public:
-    MsgNetwork(const EventContext &eb,
+    MsgNetwork(const EventContext &ec,
             int max_listen_backlog,
             double conn_server_timeout,
             size_t seg_buff_size):
-        ConnPool(eb, max_listen_backlog,
+        ConnPool(ec, max_listen_backlog,
                     conn_server_timeout,
                     seg_buff_size) {}
 
@@ -197,14 +197,14 @@ class ClientNetwork: public MsgNetwork<OpcodeType> {
     using conn_t = RcObj<Conn>;
 
     protected:
-    ConnPool::conn_t create_conn() override { return (new Conn())->self(); }
+    ConnPool::Conn *create_conn() override { return new Conn(); }
 
     public:
-    ClientNetwork(const EventContext &eb,
+    ClientNetwork(const EventContext &ec,
                 int max_listen_backlog = 10,
                 double conn_server_timeout = 0,
                 size_t seg_buff_size = 4096):
-        MsgNet(eb, max_listen_backlog,
+        MsgNet(ec, max_listen_backlog,
                 conn_server_timeout,
                 seg_buff_size) {}
 
@@ -268,10 +268,10 @@ class PeerNetwork: public MsgNetwork<OpcodeType> {
         bool connected;
 
         Peer() = delete;
-        Peer(NetAddr addr, conn_t conn, const EventContext &eb):
+        Peer(NetAddr addr, conn_t conn, const EventContext &ec):
             addr(addr), conn(conn),
             ev_ping_timer(
-                Event(eb, -1, 0, std::bind(&Peer::ping_timer, this, _1, _2))),
+                Event(ec, -1, 0, std::bind(&Peer::ping_timer, this, _1, _2))),
             connected(false) {}
         ~Peer() {}
         Peer &operator=(const Peer &) = delete;
@@ -329,13 +329,13 @@ class PeerNetwork: public MsgNetwork<OpcodeType> {
     void start_active_conn(const NetAddr &paddr);
 
     protected:
-    ConnPool::conn_t create_conn() override { return (new Conn())->self(); }
+    ConnPool::Conn *create_conn() override { return new Conn(); }
     virtual double gen_conn_timeout() {
         return gen_rand_timeout(retry_conn_delay);
     }
 
     public:
-    PeerNetwork(const EventContext &eb,
+    PeerNetwork(const EventContext &ec,
                 int max_listen_backlog = 10,
                 double retry_conn_delay = 2,
                 double conn_server_timeout = 2,
@@ -343,7 +343,7 @@ class PeerNetwork: public MsgNetwork<OpcodeType> {
                 double ping_period = 30,
                 double conn_timeout = 180,
                 IdentityMode id_mode = IP_PORT_BASED):
-        MsgNet(eb, max_listen_backlog,
+        MsgNet(ec, max_listen_backlog,
                     conn_server_timeout,
                     seg_buff_size),
         id_mode(id_mode),
@@ -432,7 +432,7 @@ template<typename O, O _, O __>
 void PeerNetwork<O, _, __>::Conn::on_setup() {
     auto pn = get_net();
     assert(!ev_timeout);
-    ev_timeout = Event(pn->eb, -1, 0, [this](evutil_socket_t, short) {
+    ev_timeout = Event(pn->ec, -1, 0, [this](evutil_socket_t, short) {
         SALTICIDAE_LOG_INFO("peer ping-pong timeout");
         this->terminate();
     });
@@ -455,7 +455,7 @@ void PeerNetwork<O, _, __>::Conn::on_teardown() {
     SALTICIDAE_LOG_INFO("connection lost %s for %s",
             std::string(*this).c_str(),
             std::string(peer_id).c_str());
-    p->ev_retry_timer = Event(pn->eb, -1, 0,
+    p->ev_retry_timer = Event(pn->ec, -1, 0,
             [pn, peer_id = this->peer_id](evutil_socket_t, short) {
         pn->start_active_conn(peer_id);
     });
@@ -546,7 +546,7 @@ void PeerNetwork<O, _, __>::add_peer(const NetAddr &addr) {
     auto it = id2peer.find(addr);
     if (it != id2peer.end())
         throw PeerNetworkError("peer already exists");
-    id2peer.insert(std::make_pair(addr, new Peer(addr, nullptr, this->eb)));
+    id2peer.insert(std::make_pair(addr, new Peer(addr, nullptr, this->ec)));
     peer_list.push_back(addr);
     start_active_conn(addr);
 }
diff --git a/src/conn.cpp b/src/conn.cpp
index bfd7c30..5897c9e 100644
--- a/src/conn.cpp
+++ b/src/conn.cpp
@@ -131,15 +131,17 @@ void ConnPool::accept_client(evutil_socket_t fd, short) {
 
         NetAddr addr((struct sockaddr_in *)&client_addr);
         conn_t conn = create_conn();
-        Conn *conn_ptr = conn.get();
+        conn->self_ref = conn;
         conn->seg_buff_size = seg_buff_size;
         conn->fd = client_fd;
         conn->cpool = this;
         conn->mode = Conn::PASSIVE;
         conn->addr = addr;
-        conn->ev_read = Event(eb, client_fd, EV_READ,
+
+        Conn *conn_ptr = conn.get();
+        conn->ev_read = Event(ec, client_fd, EV_READ,
                                 std::bind(&Conn::recv_data, conn_ptr, _1, _2));
-        conn->ev_write = Event(eb, client_fd, EV_WRITE,
+        conn->ev_write = Event(ec, client_fd, EV_WRITE,
                                 std::bind(&Conn::send_data, conn_ptr, _1, _2));
         conn->ev_read.add();
         conn->ev_write.add();
@@ -154,9 +156,9 @@ void ConnPool::Conn::conn_server(evutil_socket_t fd, short events) {
     auto conn = self(); /* pin the connection */
     if (send(fd, "", 0, MSG_NOSIGNAL) == 0)
     {
-        ev_read = Event(cpool->eb, fd, EV_READ,
+        ev_read = Event(cpool->ec, fd, EV_READ,
                 std::bind(&Conn::recv_data, this, _1, _2));
-        ev_write = Event(cpool->eb, fd, EV_WRITE,
+        ev_write = Event(cpool->ec, fd, EV_WRITE,
                 std::bind(&Conn::send_data, this, _1, _2));
         ev_read.add();
         ev_write.add();
@@ -193,7 +195,7 @@ void ConnPool::listen(NetAddr listen_addr) {
         throw ConnPoolError(std::string("binding error"));
     if (::listen(listen_fd, max_listen_backlog) < 0)
         throw ConnPoolError(std::string("listen error"));
-    ev_listen = Event(eb, listen_fd, EV_READ,
+    ev_listen = Event(ec, listen_fd, EV_READ,
             std::bind(&ConnPool::accept_client, this, _1, _2));
     ev_listen.add();
     SALTICIDAE_LOG_INFO("listening to %u", ntohs(listen_addr.port));
@@ -225,6 +227,7 @@ ConnPool::conn_t ConnPool::connect(const NetAddr &addr) {
     if (fcntl(fd, F_SETFL, O_NONBLOCK) == -1)
         throw ConnPoolError(std::string("unable to set nonblocking socket"));
     conn_t conn = create_conn();
+    conn->self_ref = conn;
     conn->seg_buff_size = seg_buff_size;
     conn->fd = fd;
     conn->cpool = this;
@@ -245,7 +248,7 @@ ConnPool::conn_t ConnPool::connect(const NetAddr &addr) {
     }
     else
     {
-        conn->ev_connect = Event(eb, fd, EV_WRITE,
+        conn->ev_connect = Event(ec, fd, EV_WRITE,
                     std::bind(&Conn::conn_server, conn.get(), _1, _2));
         conn->ev_connect.add_with_timeout(conn_server_timeout);
 
diff --git a/test/.gitignore b/test/.gitignore
index 9b5c5f5..b514e8d 100644
--- a/test/.gitignore
+++ b/test/.gitignore
@@ -1,3 +1,4 @@
 test_msg
 test_stream
+test_network
 Makefile
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index 7af1f87..f84384d 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -25,3 +25,6 @@ target_link_libraries(test_msg salticidae_static)
 
 add_executable(test_stream test_stream.cpp)
 target_link_libraries(test_stream salticidae_static)
+
+add_executable(test_network test_network.cpp)
+target_link_libraries(test_network salticidae_static)
diff --git a/test/test_network.cpp b/test/test_network.cpp
new file mode 100644
index 0000000..da72b93
--- /dev/null
+++ b/test/test_network.cpp
@@ -0,0 +1,157 @@
+/**
+ * Copyright (c) 2018 Cornell University.
+ *
+ * Author: Ted Yin <tederminant@gmail.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is furnished to do
+ * so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include <cstdio>
+#include <string>
+
+#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 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) {}
+};
+
+using MsgNetworkByteOp = MsgNetwork<opcode_t>;
+
+struct MyNet: public MsgNetworkByteOp {
+    const std::string name;
+    const NetAddr peer;
+
+    MyNet(const salticidae::EventContext &ec,
+            const std::string name,
+            const NetAddr &peer):
+        MsgNetwork<opcode_t>(ec, 10, 1.0, 4096),
+        name(name),
+        peer(peer) {}
+
+    struct Conn: public MsgNetworkByteOp::Conn {
+        MyNet *get_net() { return static_cast<MyNet *>(get_pool()); }
+        salticidae::RcObj<Conn> self() {
+            return salticidae::static_pointer_cast<Conn>(
+                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<Conn>;
+
+    salticidae::ConnPool::Conn *create_conn() override {
+        return new Conn();
+    }
+};
+
+
+void on_receive_hello(MsgHello &&msg, MyNet::conn_t conn) {
+    auto net = conn->get_net();
+    printf("[%s] %s says %s\n",
+            net->name.c_str(),
+            msg.name.c_str(), msg.text.c_str());
+    /* send acknowledgement */
+    net->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);
+
+    /* register the message handler */
+    alice.reg_handler(on_receive_hello);
+    alice.reg_handler(on_receive_ack);
+    bob.reg_handler(on_receive_hello);
+    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;
+}