This project is a sub-project of the larger Flow-IPC meta-project. Please see
a similar README.md for Flow-IPC, first. You can most likely find it either in the parent
directory to this one; or else in a sibling GitHub repository named ipc.git.
A more grounded description of the various sub-projects of Flow-IPC, including this one, can be found
in ./src/ipc/common.hpp off the directory containing the present README. Look for
Distributed sub-components (libraries) in a large C++ comment.
Took a look at those? Still interested in ipc_session as an independent entity? Then read on.
Before you do though: it is, typically, both easier and more functional to simply treat Flow-IPC as a whole.
To do so it is sufficient to never have to delve into topics discussed in this README. In particular
the Flow-IPC generated documentation guided Manual + Reference are monolithic and cover all the
sub-projects together, including this one.
Still interested? Then read on.
ipc_session depends on ipc_transport_structured (and all its dependencies; i.e. ipc_core, flow). It provides
ipc::session (excluding ipc::session::shm).
It is possible to use the structured layer of ipc::transport, namely the big daddy transport::struc::Channel,
without any help from ipc::session. (It's also possible to establish unstructured transport::Channel and
the various lower-level IPC pipes it might comprise.) And, indeed,
once a given struc::Channel (or Channel) is "up," one can and should
simply use it to send/receive stuff. The problem that ipc::session solves is in establishing
the infrastructure that makes it simple to (1) open new struc::Channels or Channels or SHM areas;
and (2) properly deal with process lifecycle events such as the starting and ending (gracefully or otherwise) of
the local and partner process.
Regarding (1), in particular (just to give a taste of what one means):
- What underlying low-level transports will we even be using? MQs? Local (Unix domain) stream sockets? Both?
- For each of those, we must connect or otherwise establish each one. In the case of MQs, say, there has
to be an agreed-upon
util::Shared_namefor the MQ in each direction... so what is that name? How to prevent collisions in this name?
While ipc::transport lets one do whatever one wants, with great flexibility, ipc::session establishes conventions
for all these things -- typically hiding/encapsulating them away.
Regarding (2) (again, just giving a taste):
- To what process are we even talking? What if we want to talk to 2, or 3, processes? What if we want to talk to 1+ processes of application X and 1+ processes of application Y? How might we segregate the data between these?
- What happens if 1 of 5 instances of application X, to whom we're speaking, goes down? How to ensure cleanup
of any kernel-persistence resources, such as the potentially used POSIX MQs, or even of SHM (
ipc::shm)?
Again -- ipc::session establishes conventions for these lifecycle matters and provides key utilities such as
kernel-persistent resource cleanup.
There can be good reasons to use ipc::transport without ipc_session (though probably fewer good ones
when using ipc::transport::Channel or ipc::transport::struc::Channel); but generally speaking
using ipc_session will save lots and lots of pain. We would even claim that it's the kind of pain
one takes for granted when doing IPC, classically; so when it goes away, it feels quite nice.
See Flow-IPC meta-project's README.md Documentation section. ipc_session lacks its own generated documentation.
However, it contributes to the aforementioned monolithic documentation through its many comments which can
(of course) be found directly in its code (./src/ipc/...). (The monolithic generated documentation scans
these comments using Doxygen, combined with its siblings' comments... and so on.)
- As a tarball/zip: The project web site links to individual releases with notes, docs, download links. We are included in a subdirectory off the Flow-IPC root.
- Via Git:
git clone --recurse-submodules [email protected]:Flow-IPC/ipc.git; orgit clone [email protected]:Flow-IPC/ipc_session.git
See INSTALL guide.
See CONTRIBUTING guide.