.. index:: pair: class; EE::System::IPC .. _doxid-class_e_e_1_1_system_1_1_i_p_c: class EE::System::IPC ===================== .. toctree:: :hidden: enum_EE_System_IPC_Status.rst Overview ~~~~~~~~ A named, local, same-user, message-oriented inter-process channel. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block #include class IPC: private :ref:`EE::NonCopyable` { public: // typedefs typedef std::function :ref:`MessageFn`; // enums enum :ref:`Status`; // fields static constexpr std::size_t :ref:`MaxMessageSize` = 16* 1024* 1024; // construction :ref:`~IPC`(); // methods :ref:`Status` :ref:`listen`(std::string_view endpoint, :ref:`MessageFn` callback); void :ref:`close`(); bool :ref:`isListening`() const; static :ref:`Status` :ref:`send`(std::string_view endpoint, const void* data, std::size_t size, :ref:`Time` timeout = :ref:`Seconds`(2)); static :ref:`Status` :ref:`send`(std::string_view endpoint, std::string_view message, :ref:`Time` timeout = :ref:`Seconds`(2)); }; .. _details-class_e_e_1_1_system_1_1_i_p_c: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ A named, local, same-user, message-oriented inter-process channel. :ref:`listen() ` starts a receiver thread. Message callbacks execute on that thread and callers are responsible for dispatching to another thread when required. Each :ref:`send() ` creates one connection, transfers one complete framed message, and disconnects. Typedefs -------- .. index:: pair: typedef; MessageFn .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1ad2aad22e43233e868ff17578336f7903: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef std::function 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 ------ .. index:: pair: variable; MaxMessageSize .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1a5fbd46b2755b351266c56a91d401c784: .. ref-code-block:: cpp :class: doxyrest-title-code-block static constexpr std::size_t MaxMessageSize = 16* 1024* 1024 Maximum accepted payload size, excluding the transport frame header. Construction ------------ .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1a0a9f24cc591e4afc362c24df3de03438: .. ref-code-block:: cpp :class: doxyrest-title-code-block ~IPC() Stops the listener, waits for its worker thread, and releases its native endpoint. Methods ------- .. index:: pair: function; listen .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1a3e1e1dbe300b8ec257a15d328ace469b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Status` listen(std::string_view endpoint, :ref:`MessageFn` callback) Starts listening on a logical endpoint. The endpoint is mapped synchronously to a platform-native, same-user local :ref:`IPC ` address; the borrowed logical name is not retained. Only one :ref:`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 :ref:`listen() ` on an instance that is already listening closes its current endpoint first. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - endpoint - Borrowed logical endpoint name. Native paths or handles are not exposed. * - callback - Function invoked on the :ref:`IPC ` worker thread for each complete message. .. rubric:: 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. .. index:: pair: function; close .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1a6c3f5827512bf750399e413ad3482b17: .. ref-code-block:: cpp :class: doxyrest-title-code-block 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. .. index:: pair: function; isListening .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1a072f93783d4311174e1da9424ab2374e: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool isListening() const .. rubric:: Returns: Whether this instance currently owns a listening endpoint. .. index:: pair: function; send .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1ad2de6b9e7d21d52458aaf66fb2ea6b18: .. ref-code-block:: cpp :class: doxyrest-title-code-block static :ref:`Status` send(std::string_view endpoint, const void* data, std::size_t size, :ref:`Time` timeout = :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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. .. rubric:: Returns: A portable status describing delivery or connection failure. .. index:: pair: function; send .. _doxid-class_e_e_1_1_system_1_1_i_p_c_1a2bff2c5bf99eeb5bdfba7e84a9b3e325: .. ref-code-block:: cpp :class: doxyrest-title-code-block static :ref:`Status` send(std::string_view endpoint, std::string_view message, :ref:`Time` timeout = :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - endpoint - Borrowed logical destination endpoint name. * - message - Borrowed payload bytes. * - timeout - Maximum time to wait for the destination connection. .. rubric:: Returns: A portable status describing delivery or connection failure.