class EE::System::IPC

Overview

A named, local, same-user, message-oriented inter-process channel. More…

#include <ipc.hpp>

class IPC: private EE::NonCopyable {
public:
    // typedefs

    typedef std::function<void(const void*, std::size_t)> MessageFn;

    // enums

    enum Status;

    // fields

    static constexpr std::size_t MaxMessageSize = 16* 1024* 1024;

    // construction

    ~IPC();

    // methods

    Status listen(std::string_view endpoint, MessageFn callback);
    void close();
    bool isListening() const;
    static Status send(std::string_view endpoint, const void* data, std::size_t size, Time timeout = Seconds(2));
    static Status send(std::string_view endpoint, std::string_view message, Time timeout = Seconds(2));
};

Detailed Documentation

A named, local, same-user, message-oriented inter-process channel.

listen() starts a receiver thread. Message callbacks execute on that thread and callers are responsible for dispatching to another thread when required. Each send() creates one connection, transfers one complete framed message, and disconnects.

Typedefs

typedef std::function<void(const void*, std::size_t)> MessageFn

Callback invoked for each complete message received by a listener.

The callback runs on the listener’s worker thread. data remains valid only for the duration of the callback and may contain embedded NUL bytes. For an empty message, data is still a valid pointer and size is zero.

Fields

static constexpr std::size_t MaxMessageSize = 16* 1024* 1024

Maximum accepted payload size, excluding the transport frame header.

Construction

~IPC()

Stops the listener, waits for its worker thread, and releases its native endpoint.

Methods

Status listen(std::string_view endpoint, MessageFn callback)

Starts listening on a logical endpoint.

The endpoint is mapped synchronously to a platform-native, same-user local IPC address; the borrowed logical name is not retained. Only one IPC instance can listen on a given endpoint at a time. A successful call starts one worker thread and invokes callback once for every complete framed message. Calling listen() on an instance that is already listening closes its current endpoint first.

Parameters:

endpoint	Borrowed logical endpoint name. Native paths or handles are not exposed.
callback	Function invoked on the IPC worker thread for each complete message.

Returns:

Done on success, AlreadyExists when the endpoint is owned by another listener, InvalidEndpoint for an empty/invalid endpoint or callback, or Error on a native failure.

void close()

Stops listening and releases the endpoint.

This function interrupts pending native waits, joins the worker thread, and guarantees that the callback will not run after it returns. Repeated calls are safe.

bool isListening() const

Returns:

Whether this instance currently owns a listening endpoint.

static Status send(std::string_view endpoint, const void* data, std::size_t size, Time timeout = Seconds(2))

Sends one binary message to a logical endpoint.

A successful call creates a connection, writes exactly one versioned frame containing size bytes, and disconnects. Embedded NUL bytes and zero-length messages are supported. The timeout applies while establishing or waiting for the destination connection.

Parameters:

endpoint	Borrowed logical destination endpoint name.
data	Payload bytes. May be null only when size is zero.
size	Payload size in bytes, up to MaxMessageSize.
timeout	Maximum time to wait for the destination connection.

Returns:

A portable status describing delivery or connection failure.

static Status send(std::string_view endpoint, std::string_view message, Time timeout = Seconds(2))

Sends one string-view payload to a logical endpoint.

The complete view is sent as opaque bytes; embedded NUL bytes are preserved and no terminator is appended.

Parameters:

endpoint	Borrowed logical destination endpoint name.
message	Borrowed payload bytes.
timeout	Maximum time to wait for the destination connection.

Returns:

A portable status describing delivery or connection failure.