MANUAL NAVIGATION: Preceding Page - Table of Contents - Reference

Overall, the ipc::transport namespace can be divided into two parts:

Lower layer (unstructured transport): ipc::transport, excluding ipc::transport::struc sub-namespace.
Higher layer (structured transport): ipc::transport::struc.

W/r/t these: This guided Manual has, so far, focused in-depth on the higher layer (Structured Message Transport (Structured Channels), Structured Message Transport: Messages As Long-lived Data Structures / Advanced Topics, Zero-copy capnp-RPC, Shared Memory: Direct Allocation, Transport). Many users, we suspect, would prefer to transmit data through that layer. It is natural to transmit structured data; ipc::transport::struc::Channel (Structured Message Transport (Structured Channels)) is a relatively simple request-response-mux-demux approach to this, while capnp-RPC (Zero-copy capnp-RPC) lets one use powerful RPC semantics.

Deciding to work exclusively with such structured data – in our case, necessarily expressed through Cap'n Proto (capnp) schemas – is not universal. Whether for performance, simplicity, or other reasons, it can make sense to work at the lower layer. For example, perhaps you'd like to just exchange simple messages over a Unix domain socket or a POSIX message queue (MQ). Or perhaps you'd like to add structured-data support that is not capnp-based.

The synopsis in API Overview page of this Manual contains a reasonable map, with representative code snippets, of this unstructured-transport layer.

The relevant Reference section documents each individual thing in detail. The class and method doc headers for the concepts ipc::transport::Native_handle_sender and ipc::transport::Native_handle_receiver are of interest, including some foundational design decisions and rationale. (Their simpler siblings Blob_sender and Blob_receiver are basically a subset: similar capabilities, just without transmission of native handles – only data blobs.) These are concepts; of their concrete implementations ipc::transport::Native_socket_stream may be of particular interest, as it implements all 4 concepts and provides access to the popular Unix-domain (local) socket IPC-transport.

Note: Reminder: there are ipc::transport::sync_io counterparts to these concepts and relevant impls; one may choose either type for one's application/event loop. (E.g., there is transport::Native_socket_stream and its sync_io-core counterpart transport::sync_io::Native_socket_stream.) See Asynchronicity and Integrating with Your Event Loop for background on event loop integration, including discussion of async-I/O-pattern APIs (directly in ipc::transport here) versus sync_io-pattern APIs (in ipc::transport::sync_io here).

Stats: Each unstructured transport keeps stats per direction: ipc::transport::stat::Blob_snd_stats and ipc::transport::stat::Blob_rcv_stats, via blob_send_stats(), blob_receive_stats(), native_handle_send_stats(), native_handle_receive_stats() (each with a *_reset()); ipc::transport::Channel forwards these. (See the stats synopsis for the general approach.)

At this time we feel the above-linked, directly or indirectly, resources are sufficient documentation for this lower-level set of APIs. Thus we forego a step-by-step tutorial here.

MANUAL NAVIGATION: Preceding Page - Table of Contents - Reference