C++

Run the server in one process, then the client in another; fipc::stream_connect waits up to its timeout for a server to create the stream and accept. A result converts to true when it holds a value, and -> reaches it. The pair makes the exchange every example on this site makes, the message ping, answered in upper case: this client works with any language's server, and this server with any language's client (every pair of languages is tested).

#include <cctype>
#include <string>

#include <fipc.hpp>

int main()
{
    auto listener = fipc::stream_create("my_channel", 1 << 20);  // rings of 1 MiB each way
    if (!listener)
        return 1;
    auto conn = listener->accept();  // waits for a client
    if (!conn)
        return 1;
    std::string message;
    if (!conn->receive(message))
        return 1;
    for (char& c : message)
        c = static_cast<char>(std::toupper(static_cast<unsigned char>(c)));
    return conn->send(message) ? 0 : 1;
}

#include <chrono>
#include <cstdio>
#include <string>

#include <fipc.hpp>

int main()
{
    auto conn = fipc::stream_connect("my_channel", std::chrono::seconds(5));
    if (!conn)
    {
        std::fprintf(stderr, "connect: %s\n", conn.error().name());
        return 1;
    }
    std::string reply;
    if (!conn->send("ping") || !conn->receive(reply))
        return 1;
    std::printf("%s\n", reply.c_str());  // PING
    return 0;
}

A connection carries messages of any size (at least one byte). send takes a std::string_view or a std::span<const std::byte>. receive fills a std::string or std::vector, resized to the message, whose capacity carries over to the next; receive_into fills a fixed buffer and returns the length.

if (!conn.send("hello"))  // std::string_view
    return 1;
std::vector<std::byte> data = encode(state);
if (!conn.send(data))  // std::span<const std::byte>
    return 1;

char buf[256];
auto len = conn.receive_into(buf);
if (!len && len.error() == fipc::errc::too_large)
{
    // nothing was taken: make room, then again
    std::vector<char> big(len.error().len);
    len = conn.receive_into(big);
}

Write into a fipc::send_slot of the ring and commit() it; a slot destroyed without its commit sends nothing. Read a fipc::receive_slot of the ring, which frees its room when destroyed. While a slot lives, its side of the connection makes no other call, and it must not outlive the connection; a slot whose turn a later acquire ended does nothing.

if (auto slot = conn.send_acquire(64))  // room in the ring
{
    int n = std::snprintf(reinterpret_cast<char*>(slot->data()), slot->size(), "tick %d", tick);
    if (!slot->commit(static_cast<std::size_t>(n)))  // publishes n bytes
        return 1;
}

if (auto message = conn.receive_acquire())  // read-only, in the ring
    handle(message->bytes());  // std::span<const std::byte>
// destroyed here: its room is free again

A broadcast sends every message of one publisher to each of its subscribers, in any processes of the user; each message is stored once, in memory every subscriber maps. Messages are of one piece, up to a quarter of the capacity. fipc::broadcast_create returns the publisher's fipc::connection; the publisher's process admits the subscribers on a thread of the library's, so no thread of yours waits for them. The publisher waits for the first one (publisher->wait_for_members(1)) before it sends tick 1 to tick 3; destroying the publisher ends the broadcast and frees the name. The subscriber joins gated (fipc::broadcast_join with fipc::subscriber_role::gated), so it misses nothing (the publisher waits for it), and receives until errc::disconnected, which comes after the last message. A lossy subscriber (fipc::subscriber_role::lossy) never holds the publisher back: one that falls a lap behind gets errc::overrun, with the number of messages lost in error().len. A gated one that holds the publisher back for the broadcast's max_stall is unsubscribed (errc::unsubscribed).

#include <chrono>
#include <string>

#include <fipc.hpp>

int main()
{
    // 64 KiB of messages, up to 8 subscribers; one that holds the publisher back 5 s is dropped
    auto publisher = fipc::broadcast_create("my_broadcast", 1 << 16, 8, std::chrono::seconds(5));
    if (!publisher)
        return 1;
    if (publisher->wait_for_members(1))  // waits for the first subscriber
    {
        for (int i = 1; i <= 3; i++)
            (void) publisher->send("tick " + std::to_string(i));
    }
    return 0;  // closing the publisher ends the broadcast: subscribers get FIPC_DISCONNECTED after the ticks
}

#include <chrono>
#include <cstdio>
#include <string>

#include <fipc.hpp>

int main()
{
    // gated: misses nothing (the publisher waits for it)
    auto subscriber = fipc::broadcast_join("my_broadcast", fipc::subscriber_role::gated, std::chrono::seconds(5));
    if (!subscriber)
    {
        std::fprintf(stderr, "join: %s\n", subscriber.error().name());
        return 1;
    }
    std::string tick;
    for (;;)
    {
        auto received = subscriber->receive(tick);
        if (!received)  // errc::disconnected: the publisher closed
            return received.error() == fipc::errc::disconnected ? 0 : 1;
        std::printf("%s\n", tick.c_str());  // tick 1, tick 2, tick 3
    }
}

A work queue takes messages from up to 63 producers and hands each to one of up to 64 consumers, in any processes of the user. Each producer has a ring of its own; a consumer takes a message of any producer, and the queue promises no order. Messages are of one piece, up to a quarter of the capacity, and wait in the queue until a consumer takes them. Each message goes to one consumer, and again, to another, only if that consumer's process ends before acknowledging it (delivery, below). Here the producer creates the queue (fipc::queue_create: a fipc::queue) and joins it as its producer with fipc::queue_join, as any process does: the owner's process admits every joiner on a thread of the library's, so the thread that created the queue may join it. It sends job 1 to job 3 and waits for the consumer (queue->wait_for_members). The fipc::queue is the queue: destroying it ends the queue, so keep it while the queue is used; the consumer receives what is left, then errc::disconnected. Other processes join with fipc::queue_join (fipc::queue_role::producer, fipc::queue_role::consumer); a member's destruction never ends the queue.

#include <chrono>
#include <string>

#include <fipc.hpp>

int main()
{
    // 4 KiB of messages per producer, 1 producer and 1 consumer: this process owns the queue and is its producer
    auto queue = fipc::queue_create("my_queue", 4096, 1, 1);
    if (!queue)
        return 1;
    auto producer = fipc::queue_join("my_queue", fipc::queue_role::producer, std::chrono::seconds(5));
    if (!producer)
        return 1;
    for (int i = 1; i <= 3; i++)
        (void) producer->send("job " + std::to_string(i));          // waits in the queue until a consumer takes it
    (void) queue->wait_for_members(fipc::queue_role::consumer, 1);  // waits for the consumer to join
    producer->close();
    return 0;  // closing the queue ends it: the consumer gets FIPC_DISCONNECTED after the jobs
}

#include <chrono>
#include <cstdio>
#include <string>

#include <fipc.hpp>

int main()
{
    auto consumer = fipc::queue_join("my_queue", fipc::queue_role::consumer, std::chrono::seconds(5));
    if (!consumer)
    {
        std::fprintf(stderr, "join: %s\n", consumer.error().name());
        return 1;
    }
    std::string job;
    for (;;)
    {
        auto received = consumer->receive(job);
        if (!received)  // errc::disconnected: the queue ended
            return received.error() == fipc::errc::disconnected ? 0 : 1;
        std::printf("%s\n", job.c_str());  // job 1, job 2, job 3
    }
}

Delivery. Each message goes to one consumer. It goes again, to another consumer, only if the process of the consumer that took it ends before acknowledging it, and when a consumer acknowledges is its own choice, not the queue's. A message received in place is acknowledged at its release (or the consumer's next receive, or its close).

• Choose by the work, per consumer. Work that may safely run twice (rendering, a computation, re-indexing, converting a file) acknowledges after it; work whose effects must never repeat (a payment, an email, a motor command) acknowledges before it.
• Not covered: a consumer that hangs while its process runs (there are no timeouts, by design); the owner's process, with which the queue ends; a reboot. A consumer holds at most one unacknowledged message at a time, the one received in place.
• A message that goes again comes in no set order, after messages its producer sent later: the queue promises no order anyway.
• A message held in place holds back its producer's room until its release: a consumer that acknowledges after a long job keeps that message's room, and so the room of the producer's messages after it, until then.
• A message that crashes every consumer that takes it, acknowledged after the work, goes to each consumer in turn, with no limit: acknowledge before the work where that can happen.

A service takes requests from up to 64 clients and hands each to one of up to 64 servers, in any processes of the user; the server that took a request replies to it, and a client receives its replies in the order of its requests. Here the server creates the service (fipc::service_create: a fipc::service) and joins it as its server with fipc::service_join (fipc::service_role::server) and answers three requests with their uppercase; destroying the fipc::service ends the service. The client joins (fipc::service_role::client) and calls ping 1 to ping 3: call() sends a request and receives its reply, and the client prints each. A request whose server ended before it replied gets errc::abandoned.

#include <cctype>
#include <chrono>
#include <string>

#include <fipc.hpp>

int main()
{
    // 4 KiB per client, requests and replies of up to 256 bytes, 1 client and 1 server: this process owns the service
    // and is its server
    auto service = fipc::service_create("my_service", 4096, 256, 1, 1);
    if (!service)
        return 1;
    auto server = fipc::service_join("my_service", fipc::service_role::server, std::chrono::seconds(5));
    if (!server)
        return 1;
    std::string request;
    for (int i = 1; i <= 3; i++)  // three requests, then the end
    {
        if (!server->receive(request))  // the next request of any client
            return 1;
        for (char& c : request)
            c = static_cast<char>(std::toupper(static_cast<unsigned char>(c)));
        if (!server->send(request))  // the reply goes to its client, and never waits
            return 1;
    }
    server->close();
    return 0;  // destroying the service ends it: the client still receives the replies sent
}

#include <chrono>
#include <cstdio>
#include <string>

#include <fipc.hpp>

int main()
{
    auto client = fipc::service_join("my_service", fipc::service_role::client, std::chrono::seconds(5));
    if (!client)
    {
        std::fprintf(stderr, "join: %s\n", client.error().name());
        return 1;
    }
    std::string reply;
    for (int i = 1; i <= 3; i++)
    {
        // sends the request and receives its reply; errc::abandoned if the server ended before it replied
        auto called = client->call("ping " + std::to_string(i), reply);
        if (!called)
        {
            std::fprintf(stderr, "call: %s\n", called.error().name());
            return 1;
        }
        std::printf("%s\n", reply.c_str());  // PING 1, PING 2, PING 3
    }
    return 0;
}

The calls. A service's connections are fipc::connections, and what each call does depends on the role. Requests and replies are of one piece, 1 to max_message bytes, the owner's choice at fipc::service_create (1 to a quarter of the capacity); max_piece() returns it on both roles.

• Replies come back in the order of the requests, so the n-th reply a client receives answers its n-th request, and a request carries no id. A client may send several requests before it receives, as many as its ring has room for, and the servers work on them at once. A receive that times out or is cancelled leaves its reply to come: the next receive returns it.
• call(request, reply, timeout) never returns another request's reply. A call checks its request first: errc::invalid for an empty one, errc::too_large over max_piece(), at once, even while a reply is owed. Then a call on a cancelled connection returns errc::cancelled at once, whatever its timeout, and sends nothing: it could never receive the reply. The connection keeps count of the replies still owed: a call whose receive timed out or was cancelled leaves its reply owed, and the next call first receives and drops that reply (at most one is owed, since every call drops it first; an errc::abandoned in its place counts too), within its own timeout and before it sends. A call that had to drop an owed reply first sends its request only if its timeout has time left: once a positive timeout has run out, it returns errc::timeout without sending, so no server sees that request; with fipc::no_wait no step waits, and it sends if there is room. After a call that gave up, a plain receive returns that call's late reply (or errc::abandoned) first: replies come in request order. A call returns errc::invalid while a request sent with send() (or a slot's commit()) still has its reply to be received: that reply is yours, so receive it first; on any connection other than a service's client it returns errc::invalid too. A call sends and receives, so no other thread may send or receive on the connection meanwhile.
• A server never waits for a client. A request takes room in its client's ring for itself and for its reply: its length rounded up to 64 bytes, plus max_message rounded up to 64, from its send until its reply has been received. A client that keeps sending without receiving waits for room its own replies hold.
• A server holds one request at a time: until it replies, its receives return errc::invalid. It may receive on one thread and reply on another. A pool is several servers, each a connection of its own; each takes the next request of any client. A reply to a client that has left is dropped and succeeds.
• A request is answered once: by its reply, or with errc::abandoned if the server that took it ended before it replied. An abandoned request may or may not have been carried out; the service never sends it again, and the client decides whether to. Not covered: a server that hangs while its process runs (there are no timeouts), and the owner's process, with which the service ends.
• The fipc::service is the service: destroying it (or close()) ends the service, so keep it while the service is used. Then clients' sends and servers' receives get errc::disconnected, and a client receives the replies that came before the end, in order, then errc::disconnected. A member's destruction never ends the service.

The C++ benchmark runs the C benchmark's loops through this header: their numbers agree within the noise, so the wrapper adds nothing measurable (details).