Overview • Transport • Protocol • Examples • Installation • Across Dockers

Presentation from March 25, 2020

AlephZero is a library for message based communication between programs running on the same machine.

AlephZero's main goal is to be simple to use. Nothing is higher priority.

There is no "master" process in between your nodes that is needed to do handshakes or exchanges of any kind. All you need is the topic name.

See the Examples.

This is probably the main value of AlephZero, above similar libraries.

AlephZero uses a lot of tricks to ensure the state of all channels is consistent, even when programs die. This includes double-buffering the state of the communication channel and robustifying the locks and notification channels.

AlephZero uses shared memory across multiple processes to read and write messages, minimizing the involvement of the kernel. The kernel only really gets involved in notifying a process that a new message exists, and for that we use futex (fast user-space mutex).

TODO: Benchmarks

AlephZero, at its core, is a simple allocator on top of a contiguous region of memory. Usually, shared-memory. The allocator of choice is a circular-linked-list, which is fast, simple, and sufficient for the protocol listed below. It also plays well with the robustness requirement.

This has a number of implications. For one, this means that old messages are kept around until the space is needed. The oldest messages are always discarded before any more recent messages.

Rather than exposing the low-level transport directly, AlephZero provides a few higher level protocol:

• PubSub: Broadcast published messages. Subscribers get notified.
• RPC: Request-response.
• PRPC (Progressive RPC): Request-streaming response.

Many more example and an interactive experience can be found at: https://github.com/alephzero/playground

For the curious, here are some simple snippets to get you started:

To begin with, we need to include AlephZero:

#include <a0.h>

You can have as many publisher and subscribers on the same topic as you wish. They just need to agree on the filename.

a0::Publisher p("my_pubsub_topic");
p.pub("foo");

You just published "foo" to the "my_pubsub_topic".

To read those message, you can create a subscriber on the same topic:

a0::Subscriber sub(
    "my_pubsub_topic",
    [](a0::Packet pkt) {
      std::cout << "Got: " << pkt.payload() << std::endl;
    });

The callback will trigger whenever a message is published.

The Subscriber object spawns a thread that will read the topic and call the callback.

To avoid thread creation and manually probe for messages:

a0::SubscriberSync sub_sync("my_pubsub_topic");
while (sub_sync.can_read()) {
  auto pkt = sub_sync.read();
  std::cout << "Got: " << pkt.payload() << std::endl;
}

An optional INIT can be added to specify where the subscriber starts reading.

• INIT_AWAIT_NEW (default): Start with messages published after the creation of the subscriber.
• INIT_MOST_RECENT: Start with the most recently published message. Useful for state and configuration. But be careful, this can be quite old!
• INIT_OLDEST: Topics keep a history of 16MB (unless configures otherwise). Start with the oldest thing still in there.

An optional ITER can be added to specify how to continue reading messages. After each callback:

• ITER_NEXT (default): grab the sequentially next message. When you don't want to miss a thing.
• ITER_NEWEST: grab the newest available unread message. When you want to keep up with the firehose.

Create an RpcServer:

a0::RpcServer server(
    "my_rpc_topic",
    /* onrequest = */ [](a0::RpcRequest req) {
        std::cout << "Got: " << req.pkt().payload() << std::endl;
        req.reply("echo " + std::string(req.pkt().payload()));
    },
    /* oncancel = */ nullptr);

Create an RpcClient:

a0::RpcClient client("my_rpc_topic");
client.send("client msg", [](a0::Packet reply) {
  std::cout << "Got: " << reply.payload() << std::endl;
});

apt install g++ make

apk add g++ linux-headers make

git clone https://github.com/alephzero/alephzero.git
cd alephzero
make install -j

Coming soon-ish. Let me know if you want this and I'll prioritize it. External support is much appreciated.

Add the following to g++ / clang commands.

-L${libdir} -lalephzero -lpthread

pkg-config --cflags --libs alephzero

Coming soon-ish. Let me know if you want this and I'll prioritize it. External support is much appreciated.

Coming soon-ish. Let me know if you want this and I'll prioritize it.

For programs running across different dockers to be able to communicate, we need to have them match up on two flags: --ipc and --pid.

• --ipc shares the /dev/shm filesystem. This is necessary to open the same file topics.
• --pid shares the process id namespace. This is necessary for the locking and notification systems.

In the simplest case, you can set them both to host and talk through the system's global /dev/shm and process id namespace.

docker run --ipc=host --pid=host --name=foo foo_image
docker run --ipc=host --pid=host --name=bar bar_image

Or, you can mark one as shareable and have the others connect to it:

docker run --ipc=shareable --pid=shareable --name=foo foo_image
docker run --ipc=container:foo --pid=container:foo --name=bar bar_image