a-about.dox.txt

/* Flow-IPC
 * Copyright 2023 Akamai Technologies, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in
 * compliance with the License.  You may obtain a copy
 * of the License at
 *
 *   https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in
 * writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 * CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing
 * permissions and limitations under the License. */

/**

@mainpage Welcome to the Flow-IPC Project

The documentation you're viewing has been generated using Doxygen directly from Flow-IPC source code and comments.

The documentation is divided into two parts:
  - [Manual](./pages.html): This is a guided manual (with a gentler learning curve versus perusing the Reference top-down).
    - Begin at: @ref about "Manual Start".
    - Or visit the manual [table of contents](./pages.html) (also accessible via Related Pages menu above).
  - @link ::ipc Reference@endlink: All classes, functions, members, etc. are individually documented.
    - For a top-down look, start with the @link ::ipc documentation of namespace `ipc`@endlink, then continue to its sub-namespaces (each of which is a major module of Flow-IPC), and so on.
    - Or look up any item of interest via menus above and the search bar.
    - If it says "Full implementation reference" at the very top of this page, then the full source browser is included, and all internal item documentation is included.
      - Otherwise it is just the public API reference.

*/

/* (This "comment" is ignored by Doxygen, as it does not have the ** prefix.)
 *
 * ANNOYING NOTE: We currently rely on the Related Pages page generated by Doxygen to double as the manual
 * table of contents.  (It also includes the To-do list generated from `@todo`s.  That's fine.)
 * Doxygen appears to use the lexical order of the file names -- not the @page names or the auto-brief
 * (first sentence in @page) contents -- to determine the order items are listed in Related Pages.
 * Therefore at this time we must name the per-@page .dox.txt files as a-..., b-..., etc., to get them to show
 * up in the proper order.  There are of course other ways of making a table of contents (perhaps a @todo?), but
 * for now this works fine with mostly minimal effort. */

/**

@page about (Manual Start) Flow-IPC: Bird's-eye View

<center>**MANUAL NAVIGATION:** @ref api_overview "Next Page" - [**Table of Contents**](./pages.html) - @link ::ipc **Reference**@endlink</center>

---

@anchor fig0
@image html sessions_and_transport_high_v2.png

- On the left -- Flow-IPC's mission: applications speaking to each other performantly, in organized fashion.  The infrastructure inside the dotted-line boxes is provided by Flow-IPC.  Perhaps most centrally this offers communication *channels* over which one can transmit *messages* with a few lines of code.
- On the right -- zooming into a single *channel*; and how it transmits data of various kinds, especially without copying (therefore at high speed).
  - "capnp" stands for [Cap'n Proto](https://capnproto.org/language.html).
  - Some readers have said this diagram is too "busy."  If that's your impression: Please do not worry about the details.  It is a *survey* of what and how one *could* transmit via Flow-IPC; different details might appeal to different users.
  - Ultimately, if you've got a message or data structure to share between processes, Flow-IPC will let you do it with a few lines of code.

We hope a picture is worth a thousand words, but please do scroll down to read a few words anyway.

If you'd prefer a synopsis with code snippets, right away, try @ref api_overview.

Executive summary: Why does Flow-IPC exist?
---------------------------------------------

Multi-process microservice systems need to communicate between processes efficiently.  Existing microservice communication frameworks are elegant at a high level but can add unacceptable latency out of the box.  (This is true of even lower-level tools including the popular and powerful [gRPC](https://grpc.io/), usually written around [Protocol Buffers](https://protobuf.dev/) serialization.)  Low-level interprocess communication (*IPC*) solutions, typically custom-written on-demand to address this problem, struggle to do so comprehensively and in reusable fashion.  Teams repeatedly spend resources on challenges like structured data and session cleanup.  These issues make it difficult to break monolithic systems into more resilient multi-process systems that are also maximally performant.

Flow-IPC is a modern C++ library that solves these problems.  It adds virtually zero latency.  Structured data are represented using the high-speed Cap’n Proto (*capnp*) serialization library, which is integrated directly into our shared memory (SHM) system. The Flow-IPC SHM system extends a commercial-grade memory manager (*jemalloc*, as used by FreeBSD and Meta).  Overall, this approach eliminates all memory copying (end-to-end *zero copy*).

Flow-IPC features a session-based channel management model. A *session* is a conversation between two programs; to start talking one only needs the name of the other program.  Resource cleanup, in case of exit or failure of either program, is automatic.  Flow-IPC’s sessions are also safety-minded as to the identities and permissions at both ends of the conversation.

Flow-IPC’s API allows developers to easily adapt existing code to a multi-process model.  Instead of each dev team writing their own IPC implementation piecemeal, Flow-IPC provides a highly efficient standard that can be used across many projects.

---

Welcome to the guided Manual.  It explains how to use Flow-IPC with a gentle learning curve in mind.  It is arranged in top-down order.  (You may also be interested in the @link ::ipc Reference@endlink.)

Feature overview: What is Flow-IPC?
-----------------------------------
Flow-IPC:
  - is a **modern C++** library with a concept-based API in the spirit of STL/Boost;
  - enables near-zero-latency **zero-copy** messaging between processes (via behind-the-scenes use of the below SHM solution);
  - transmits messages containing binary data, native handles, and/or **structured data** (defined via [Cap'n Proto](https://capnproto.org/language.html));
  - provides a **shared memory (SHM)** solution
    - with out-of-the-box ability to transmit arbitrarily complex combinations of scalars, `struct`s, and **STL-compliant containers** thereof;
    - that integrates with **commercial-grade memory managers** (a/k/a `malloc()` providers).
      - In particular we integrate with [jemalloc](https://jemalloc.net), a thread-caching memory manager at the core of FreeBSD, Meta, and others.

A key feature of Flow-IPC is pain-free setup of process-to-process conversations (**sessions**), so that users need not worry about coordinating individual shared-resource naming between processes, not to mention kernel-persistent resource cleanup.

Flow-IPC provides 2 ways to integrate with your applications' event loops.  These can be intermixed.
  - The **async-I/O API** automatically starts threads as needed to offload work onto multi-processor cores.
  - The `sync_io` **API** supplies lighter-weight objects allowing you full control over each application's thread structure, hooking into reactor-style (`poll()`, `epoll_wait()`, etc.) or proactor (boost.asio) event loops.  As a result context switching is minimized.

Lastly Flow-IPC supplies **lower-level utilities** facilitating work with POSIX and SHM-based **message queues (MQs)** and **local (Unix domain) stream sockets**.

Delving deeper
--------------

The high-level diagram @ref fig0 "above" is a pretty good synopsis of the highest-impact features.  The following diagram delves deeper, roughly introducing the *core* layer of ipc::transport.  Then we begin a textual exploration in @ref api_overview.

@image html 1x1.png "Figure 1. IPC channels (core layer); SHM arenas; and your code."
@image html transport_core_v1.png

Future directions of work
-------------------------
We feel this is a comprehensive work, but there is always more to achieve.  Beyond maintenance and incremental features, here are some future-work ideas of a more strategic nature.
  - **Networked IPC**: At the moment all IPC supported by Flow-IPC is between processes within a given machine (node).  A session can only be established that way for now.  Extending this to establish IPC sessions via network would be easy.  Unix-domain-socket-based low-level transports would easily be extended to work via TCP sockets (at least).  This is a very natural next step for Flow-IPC development: a low-hanging fruit.
  - **Networked "shared memory" (RDMA)**: While the preceding bullet point would have clear utility, naturally the zero-copy aspect of the existing Flow-IPC cannot directly translate across a networked session: It is internally achieved using SHM, but there is no shared memory between two separate machines.  There *is*, however, [Remote Direct Memory Access (RDMA)](https://en.wikipedia.org/wiki/Remote_direct_memory_access): direct memory access from the memory of one computer into that of another without involving either one's OS.  While assuredly non-trivial, leveraging RDMA in Flow-IPC might allow for a major improvement over the feature in the preceding bullet point, analogously to how SHM-based zero-copy hugely improves upon basic IPC.
  - **Beyond C++**: This is a C++ project at this time, but languages including Rust and Go have gained well-deserved popularity as well.  In a similar way that (for example) Cap'n Proto's original core is in C++, but there are implementations for other languages, it would make sense for the same to happen for Flow-IPC.  There are no technical stumbling blocks for this; it is only a question of time and effort.
  - **More architectures**: As of this writing, Flow-IPC targets Linux + x86-64.  macOS/Darwin/similar support is attainable with a few weeks of work, we estimate.  (Could tackle Windows as well.)  Supporting other hardware architectures, such as ARM64, is also doable and valuable.  We'd like to do these things: by far most of the code is platform-independent, the exceptions being certain internal low-level details typically involving shared memory and pointer tagging in the SHM-jemalloc sub-component.

We welcome feedback, ideas, and (of course) pull requests of all kinds!

---

Onward!

---

<center>**MANUAL NAVIGATION:** @ref api_overview "Next Page" - [**Table of Contents**](./pages.html) - @link ::ipc **Reference**@endlink</center>

*/