libipc-old/docs/libipc.md

Before starting

This file is a presentation. Better get the point tools here: https://git.baguette.netlib.re/Baguette/pointtools

TODO: Explain the problem TODO: Explain the solution TODO: Explain why LibIPC TODO: Explain how LibIPC TODO: Explain other possible implementations TODO: Explain future of LibIPC TODO: Explain what can be done right now TODO: Explain what I actually do with it TODO: Explain LibIPC isn't a silver bullet but fine for what I want

Have fun!

Programming problems

Libraries

• change often = hard to follow
• don't often provide a high-level interface
• each library is coded in its own way
• availability vary depending on the language

Example: libraries to access databases

• languages often have their own implementation
• functions may vary from a language to another

Infrastructure problems

Infrastructure

• Always need to install all required libraries
• No clear way to sandbox part of an application

What solution?

MAKE APPLICATIONS, NOT LIBRARIES

• apps talking to apps

Create an abstraction for

libraries

• languages, implementations, code modifications in general

network code

• networking: performed by dedicated services
  • example: TCPd, UDPd, TLSd, HTTPd...
  • LibIPC is independant from protocols and formats
• applications think communications are local

In practice

usage must be simple

1. init connection or service
2. loop over events

#pause events are simple and high level

1. connection and disconnection
2. message received and sent

#pause message have a simple format: length + value

#pause And that's it.

When

LibIPC is useful when the app:

• cannot be a simple shell command
• needs a bidirectional communication
• is an abstraction over a library

Available libraries

• DBUS
• libevent
• even more complicated stuff
  • RPC-style, like Corba

#pause

• ... or bare libc api
  • shared memory
  • pipes
  • sockets (unix, inet, inet6)

DBUS

• not well suited for our needs (a polite way to say: what a bloody mess)

Is it designed NOT to be used?

• over-engineered
• complex
• documentation isn't great
  • no code example

DBUS (bonus page!)

DBUS feels obsolete: a big chunk of the documentation is about message format. Just use CBOR already!

#pause They even admit they did a poor job on the C part:

There is a low-level C binding, but that is probably too detailed and cumbersome for anything but writing other bindings.

#pause Oh. And C++. YOU SHALL NOT PASS!

This is a Linux requirement nowadays, wth?

libevent

• works with epoll and kqueue

  • great performances
  • works on Linux and *BSD

• a bit complicated

Bare libc api

shared memory and semaphores

• (kinda) complicated api
• not about exchanging messages

pipes, sockets

• lack a conventional message format ... but that's about it
• Great to start with!

All have great performances to exchange data.

What is slow is the function to wait for new events.

LibIPC's choice

Unix sockets

• fast, simple, reliable, bidirectional
• remote connections will have their own service (ex: TCPd)

Dumbest possible message format

• length + value
• build your own format on top of it!

Wait on file descriptors with poll(2)

• slow, but available everywhere
• may upgrade to libevent

LibIPC history (1/2)

1. based on pipes

• because we gotta go fast!
• ... but implementation was a bit of a mess

#pause 2. rewrite to work with unix sockets

• performances are excellent, no need for absolute best
• way nicer implementation
• select(2) for listening on file descriptors #pause
• ... wait, does select(2) support more than 1024 connections?

LibIPC history (2/2)

3. rewrite using poll(2)

• many bugfixes later, way more tested than before
• implementation was (kinda) production-ready
• implementation was simple: < 2000 lines of C code

Still wasn't as simple as I wanted

Current implementation of libIPC

Written in Zig

bindings available in Crystal

• as well as fancy mappings: JSON and CBOR class serialization

#pause epoll (Linux) and kqueue (*BSD) were avoided

• 'cause callbacks hell => harder to read and to write code #pause
• but we need them for better performances with many connections though, API should stay the same for non threaded applications (simple implementation)

#pause LibIPC doesn't handle parallelism, yet

How libIPC works

LibIPC has a high level API for the user

1. init a connection (client) or create an unix socket (service)

example: ipc_service_init (context, "service")

#pause 2. loop, wait for events listening to file descriptors (libIPC ones or not)

example:

while(1) {
  wait_event (context, &event, &timer)
  switch (event.type) {
    case IPC_CONNECTION : ...
    case IPC_DISCONNECTION : ...
    case IPC_MESSAGE: {
      struct ipc_message *m = event.m;
      ...
    }
  }
}

How libIPC works

3. send messages

    struct ipc_message m
    m.payload   = ...
    m.length    = strlen(m.payload)
    m.fd        = event.fd
    m.type      = ...
    m.user_type = ...
    ipc_write (context, &m)

#pause 4. add and remove fd from the context

ipc_add_fd (context, fd)
ipc_del_fd (context, fd)

How libIPC works

LibIPC also helps to create "protocol daemons" like TCPd with automatic switching between file descriptors

LibIPC takes callbacks to obtain libipc payloads inside arbitrary message structure

Example: websocketd. Clients exchange data with a libipc service through websockets messages.

     websocketd binds both the client and its service file descriptors,
     then provides the libipc a callback to extract libipc messages from
     the websocket messages sent by the client.

     Same thing the other way.


     ipc_switching_callbacks (context, client_fd, cb_in, cb_out)

libIPC internal structures

Main goal: simplest possible structures

Examples:

Message

struct ipc_message {
  char type;        => Internal message type, used by protocol daemons.
  char user_type;   => User-defined message type (arbitrary).
  int fd;           => File descriptor concerned about this message.
  uint32_t length;  => Payload length.
  char *payload;    => Actual payload.
};

Context of the whole networking state

struct ipc_ctx {
  struct ipc_connection_info *cinfos;  => Keeps track of connections.
  struct pollfd *pollfd;               => List of "pollfd" structures within cinfos,
                                          so we can pass it to poll(2).
  size_t size;                         => Size of the connection list.
  struct ipc_messages tx;              => Messages to send.
  struct ipc_switchings switchdb;      => Relations between fd.
};

Future of libIPC

LibIPC will be rewritten in Zig

• simpler to read and write

  • data structures are simpler to create with comptime
  • less code redundancy (more generic functions)
  • already existing error management as written in current libIPC
  • already existing loggin system
  • no more C's pitfalls

• way better at exposing bugs

  • thanks to a better type system

• way safer: cannot ignore errors

  • so I won't

• simpler to cross-compile: same standard library for every OSs

• simpler (and more secure) memory management

Also: this won't change existing bindings! No excuses!

Why not use it?

Current limitations

• performances (libIPC is based on poll(2), not epoll nor kqueue)

  • it really isn't an issue until you have hundreds or thousands of clients

• parallelism is not permitted nothing in libIPC is thread-safe

The future Zig implementation will overcome these issues.

Questions?

Ask! karchnu at karchnu.fr