aboutsummaryrefslogtreecommitdiff
path: root/README.rst
diff options
context:
space:
mode:
Diffstat (limited to 'README.rst')
-rw-r--r--README.rst171
1 files changed, 171 insertions, 0 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;
+ }