aboutsummaryrefslogtreecommitdiff
path: root/README.rst
blob: 5cf9366bfc1cbba38ad9893d1931dd9fa85689ad (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
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`: A byte level connection pool implementation, the `ConnPool::Conn`
  (or `ConnPool::conn_t`) objects represent a connection to which one can
  send/receive a binary stream of data asynchronously.

- `MsgNetwork<OpcodeType>`: A message level network pool implementation, the
  `MsgNetwork::Conn` (or `MsgNetwork::cont_t`) objects represent a channel to
  which one can send/receive a predefined message. 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 vald message
  type must have `opcode` value as its static member and `serialized` as a
  member typed `DataStream` which contains the serialized data of the message.

- `PeerNetwork<OpcodeType>`: A 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 at the application layer.

- `ClientNetwork<OpcodeType>`: A simple client-server network pool
  implementation. A server who initialy 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 <cstdio>
  #include <string>
  #include <functional>
  
  #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<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) {
          /* 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<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, 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;
  }