Rust

Start the two in either order, in two terminals: fipc::stream::connect waits up to its timeout for a server to create the stream and accept. Each file is a program of its own (src/main.rs, or an example: cargo run --example server). A timeout is anything that converts into an Option<Duration>: None waits as long as it takes. 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.

fn main() -> fipc::Result<()> {
    let mut listener = fipc::stream::create("my_channel", 1 << 20)?; // rings of 1 MiB each way
    let mut conn = listener.accept(None)?; // waits for a client
    let message = conn.receive(None)?;
    conn.send(&message.to_ascii_uppercase(), None)?;
    Ok(())
}

use std::time::Duration;

fn main() -> fipc::Result<()> {
    let mut conn = fipc::stream::connect("my_channel", Duration::from_secs(5))?;
    conn.send(b"ping", None)?;
    println!("{}", String::from_utf8_lossy(&conn.receive(None)?)); // PING
    Ok(())
}

A connection carries messages: send takes a message of any size, and receive returns each one whole in a new Vec (or fills your buffer). This server echoes every message back until its client leaves, which ends its next receive with Error::Disconnected.

use fipc::Error;

fn main() -> fipc::Result<()> {
    // rings of 1 MiB each way: a power of two, 1 KiB to 2 GiB
    let mut listener = fipc::stream::create("demo", 1 << 20)?;
    let mut conn = listener.accept(None)?; // waits for a client
    loop {
        match conn.receive(None) {
            Ok(message) => conn.send(&message, None)?, // echo, any size
            Err(Error::Disconnected) => break,
            Err(e) => return Err(e),
        }
    }
    println!("client gone");
    Ok(())
}

use std::time::Duration;

fn main() -> fipc::Result<()> {
    let mut conn = fipc::stream::connect("demo", Duration::from_secs(5))?;
    for word in ["hello", "shared", "memory"] {
        conn.send(word.as_bytes(), None)?;
        println!("{}", String::from_utf8_lossy(&conn.receive(None)?));
    }
    Ok(())
}

Write into a SendSlot of the ring and commit it; read a ReceiveSlot of the ring, which frees its room when dropped. Both deref to [u8]. A slot borrows its side of the connection, so the borrow checker keeps it from outliving its turn: nothing else is sent (or received) while it lives. Dropping a SendSlot without committing it sends nothing.

let mut slot = conn.send_acquire(5, None)?; // room in the ring
slot.copy_from_slice(b"hello");
slot.commit(5)?;

let message = conn.receive_acquire(None)?; // read-only, in the ring
handle(&message);
drop(message); // frees its room

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 (max_piece()). fipc::broadcast::create returns the publisher, a Connection and the broadcast's one handle. The publisher's process admits each subscriber that joins on a thread of the library's; the publisher waits for the first one (publisher.wait_for_members(1, None), which takes &self; at a timeout the MembersError's count is the number joined) before it sends tick 1 to tick 3; dropping the publisher ends the broadcast and frees the name. The subscriber joins gated (fipc::broadcast::join with SubscriberRole::Gated), so it misses nothing (the publisher waits for it), may receive in place with the unsafe receive_acquire_gated (its memory can vanish once it is unsubscribed: drop the slot before the broadcast's max_stall, or create it with None), and receives until Error::Disconnected, which comes after the last message. A gated one that holds the publisher back for the broadcast's max_stall is unsubscribed (Error::Unsubscribed).

use std::time::Duration;

fn main() -> fipc::Result<()> {
    // 64 KiB of messages, up to 8 subscribers; one that holds the publisher back 5 s is dropped
    let mut publisher = fipc::broadcast::create("my_broadcast", 1 << 16, 8, Duration::from_secs(5))?;
    publisher.wait_for_members(1, None)?; // waits for the first subscriber
    for i in 1..=3 {
        publisher.send(format!("tick {i}").as_bytes(), None)?;
    }
    Ok(())
} // dropping the publisher ends the broadcast: subscribers get Error::Disconnected after the ticks

use fipc::{Error, SubscriberRole};
use std::time::Duration;

fn main() -> fipc::Result<()> {
    // gated: misses nothing (the publisher waits for it)
    let mut subscriber = fipc::broadcast::join("my_broadcast", SubscriberRole::Gated, Duration::from_secs(5))?;
    loop {
        match subscriber.receive(None) {
            Ok(tick) => println!("{}", String::from_utf8_lossy(&tick)), // tick 1, tick 2, tick 3
            Err(Error::Disconnected) => return Ok(()),                  // the publisher closed
            Err(e) => return Err(e),
        }
    }
}

match subscriber.receive(None) {
    Ok(message) => handle(&message),
    // Fell a lap behind: the next receive goes on from a recent message
    Err(Error::Overrun { lost }) => println!("{lost} messages lost"),
    Err(e) => return Err(e), // Error::Disconnected: the broadcast ended
}

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: the queue promises no order. Messages are of one piece, up to a quarter of the capacity (max_piece()), 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). fipc::queue::create returns the owner's Queue; producers and consumers join with fipc::queue::join (QueueRole::Producer, QueueRole::Consumer), the owner too, and the owner's process admits each one on a thread of the library's. Here the owner joins as the producer, sends job 1 to job 3, which wait in the queue, and waits for the consumer (queue.wait_for_members(QueueRole::Consumer, 1, None)). A queue lives until its Queue is closed or dropped, or the owner's process ends: then the consumer receives what is left, then Error::Disconnected, and a producer's sends return Error::Disconnected. queue.close() or the drop ends it at a place you see; nothing else does (no garbage collector): binding it to _, or not at all, drops it, and the queue ends at once. A producer's or a consumer's drop never ends the queue. A consumer receives copied or in place (receive_acquire).

use fipc::QueueRole;
use std::time::Duration;

fn main() -> fipc::Result<()> {
    // 4 KiB of messages per producer, 1 producer and 1 consumer: this process owns the queue and is its producer
    let queue = fipc::queue::create("my_queue", 4096, 1, 1)?;
    let mut producer = fipc::queue::join("my_queue", QueueRole::Producer, Duration::from_secs(5))?;
    for i in 1..=3 {
        producer.send(format!("job {i}").as_bytes(), None)?; // waits in the queue until a consumer takes it
    }
    queue.wait_for_members(QueueRole::Consumer, 1, None)?; // waits for the consumer to join
    Ok(())
} // dropping the producer, then the queue, ends the queue: the consumer gets Error::Disconnected after the jobs

use fipc::{Error, QueueRole};
use std::time::Duration;

fn main() -> fipc::Result<()> {
    let mut consumer = fipc::queue::join("my_queue", QueueRole::Consumer, Duration::from_secs(5))?;
    loop {
        match consumer.receive(None) {
            Ok(job) => println!("{}", String::from_utf8_lossy(&job)), // job 1, job 2, job 3
            Err(Error::Disconnected) => return Ok(()),                // the queue ended
            Err(e) => return Err(e),
        }
    }
}

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 the reply goes back to the client that sent it. A server waits for the requests of every client at once (one receive), and the servers of a pool share the load: each takes the next request of any client. Each client has a ring of its own, which holds its requests and the room for their replies, so a server never waits for a client. Requests and replies are of one piece, 1 to max_message bytes, the owner's choice (max_piece()). Here the server creates the service (fipc::service::create returns the owner's Service), joins it as its server (fipc::service::join with ServiceRole::Server: the owner's process admits every joiner on a thread of the library's, its own included) and answers three requests with their uppercase. The client joins (ServiceRole::Client) and calls ping 1 to ping 3: call sends a request and returns its reply. A service lives until its Service is closed or dropped, or the owner's process ends: then clients' sends and servers' receives return Error::Disconnected, and a client receives the replies that came before the end, then Error::Disconnected. service.close() or the drop ends it at a place you see; nothing else does: binding it to _, or not at all, drops it, and the service ends at once. A client's or a server's drop never ends the service.

use fipc::ServiceRole;
use std::time::Duration;

fn main() -> fipc::Result<()> {
    // 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
    let service = fipc::service::create("my_service", 4096, 256, 1, 1)?;
    let mut server = fipc::service::join("my_service", ServiceRole::Server, Duration::from_secs(5))?;
    for _ in 0..3 {
        // three requests, then the end
        let request = server.receive(None)?; // the next request of any client
        server.send(&request.to_ascii_uppercase(), None)?; // the reply goes to its client, and never waits
    }
    service.close(); // ends the service: the client still receives the replies sent
    Ok(())
}

use fipc::ServiceRole;
use std::time::Duration;

fn main() -> fipc::Result<()> {
    let mut client = fipc::service::join("my_service", ServiceRole::Client, Duration::from_secs(5))?;
    for i in 1..=3 {
        // sends the request and returns its reply; Error::Abandoned if the server ended before it replied
        let reply = client.call(format!("ping {i}").as_bytes(), None)?;
        println!("{}", String::from_utf8_lossy(&reply)); // PING 1, PING 2, PING 3
    }
    Ok(())
}

• A client's replies come in the order of its requests. send(request) sends a request (or send_acquire and the slot's commit), and a receive (receive, receive_into, or in place receive_acquire) returns the reply to its oldest request whose reply it hasn't received yet, whichever server replies first. A client may send several requests before it receives (as many as its ring has room for: each holds its length rounded up to 64 bytes, plus max_message rounded up to 64, until its reply has been received), 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, timeout) never returns another request's reply. The connection keeps count of the replies still owed: a call that timed out or was cancelled waiting for its reply leaves that reply owed, and the next call first receives and drops that reply (at most one is owed, since every call drops it first; an Error::Abandoned in its place counts too), within its own timeout and before it sends. A call checks its request first: Error::Invalid for an empty one, Error::TooLarge over max_piece(), at once, even while a reply is owed. Then a call on a cancelled connection returns Error::Cancelled at once, whatever its timeout, and sends nothing: it could never receive the reply. 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 Error::Timeout without sending, so no server sees that request; with a zero timeout 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 Error::Abandoned) first: replies come in request order. A call returns Error::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 Error::Invalid too. It takes &mut self: it sends and receives, and the borrow checker keeps another thread from doing either meanwhile.
• A server holds one request at a time. receive takes the next request of any client (each client's in the order it sent them), and send(reply) replies to it and never waits; until then its receives return Error::Invalid, and a reply with no request held returns Error::Invalid. A reply to a client that has left is dropped. A server may receive on one thread and reply on another (into_split()), and receives its next request once it has replied.
• A request in place is read before its reply, never after. From the reply on, its bytes are its client's again, and the borrow checker keeps them from being read: receive_request() returns a Request, which derefs to the request in the ring, borrows the whole connection, and is consumed by its reply, reply(&[u8]) (a copy) or reply_in_place(len, write), which hands write the request and room for the reply in the ring, apart from the request's. A Request is Send: another thread may reply. A ReceiveSlot from receive_acquire() borrows the whole connection too, so the reply waits for its drop; a server's split Receiver refuses receive_acquire() (Error::Invalid).
• Error::Abandoned: a client's receive (or call) returns it when the server that took the request ended before it replied: it was dropped, or its process ended. The request counts as answered, and the next receive returns the next reply. An abandoned request may or may not have been carried out; the service never sends it again, and the client decides whether to.
• The owner's service: service.wait_for_members(role, at_least, timeout) waits until that many members of the role (ServiceRole::Client, ServiceRole::Server, or None for both) have joined, and returns the count, or a MembersError; service.cancel() or a service.canceler() ends such a wait from any thread. Clients wait while no server is joined, and servers while no client is.
• Not covered: a server that hangs while its process runs (there are no timeouts, by design: its client waits, within its own timeouts); the owner's process, with which the service ends.

let request = server.receive_request(None)?; // held in place until the reply
let len = request.len();
request.reply_in_place(len, |request, reply| {
    reply.copy_from_slice(request); // the reply's room, apart from the request: zero-copy both ways
    reply.make_ascii_uppercase();
    len
})?;

match client.call(b"charge 42", Duration::from_secs(5)) {
    Ok(reply) => handle(&reply),
    // Its server ended before it replied: the charge may or may not have been made
    Err(Error::Abandoned) => println!("ask the ledger before trying again"),
    Err(e) => return Err(e), // Error::Disconnected: the service ended
}

The server.rs and client.rs above work with a peer in any of the ten languages: every pair of languages is tested.

Poll the connection once a frame with NO_WAIT, or give its Receiver to a thread that forwards messages through a channel the frame loop drains. In Bevy, a Connection (or the channel's receiving end) fits in a Resource and is polled in a system. game_loop.rs runs against echo_server.rs.

use fipc::{Error, NO_WAIT};
use std::time::Duration;

fn main() -> fipc::Result<()> {
    let mut conn = fipc::stream::connect("demo", Duration::from_secs(5))?;
    let mut echoes = 0;
    for frame in 0..60u32 {
        conn.send(&frame.to_le_bytes(), NO_WAIT)?; // Error::Timeout only if the ring is full
        loop {
            match conn.receive(NO_WAIT) {
                Ok(_echo) => echoes += 1,
                Err(Error::Timeout) => break, // nothing more this frame
                Err(e) => return Err(e),      // Error::Disconnected: the peer is gone
            }
        }
        std::thread::sleep(Duration::from_millis(16)); // the rest of the frame
    }
    println!("{echoes} echoes in 60 frames");
    Ok(())
}

// Sending on this thread, receiving on another: the halves of the connection
let (mut sender, mut receiver) = conn.into_split();
let reader = std::thread::spawn(move || {
    while let Ok(message) = receiver.receive(None) {
        if tx.send(message).is_err() {
            break; // the frame loop is gone
        }
    }
});
// Each frame: whatever has arrived, without waiting
sender.send(b"update", None)?;

Measured through this binding, copied 16-byte messages run at 41 to 100 million per second between two processes, and 64 KiB messages at 435,000 to 665,000 per second (details).