|
| 1 | +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 2 | +<html xmlns="http://www.w3.org/1999/xhtml"> |
| 3 | +<head> |
| 4 | +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| 5 | +<meta http-equiv="X-UA-Compatible" content="IE=11"/> |
| 6 | +<meta name="generator" content="Doxygen 1.9.4"/> |
| 7 | +<meta name="viewport" content="width=device-width, initial-scale=1"/> |
| 8 | +<title>Flow-IPC: (Manual Start) Flow-IPC: Bird's-eye View</title> |
| 9 | +<link href="tabs.css" rel="stylesheet" type="text/css"/> |
| 10 | +<script type="text/javascript" src="jquery.js"></script> |
| 11 | +<script type="text/javascript" src="dynsections.js"></script> |
| 12 | +<link href="search/search.css" rel="stylesheet" type="text/css"/> |
| 13 | +<script type="text/javascript" src="search/searchdata.js"></script> |
| 14 | +<script type="text/javascript" src="search/search.js"></script> |
| 15 | +<link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| 16 | +</head> |
| 17 | +<body> |
| 18 | +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| 19 | +<div id="titlearea"> |
| 20 | +<table cellspacing="0" cellpadding="0"> |
| 21 | + <tbody> |
| 22 | + <tr id="projectrow"> |
| 23 | + <td id="projectalign"> |
| 24 | + <div id="projectname">Flow-IPC<span id="projectnumber"> 1.0.2</span> |
| 25 | + </div> |
| 26 | + <div id="projectbrief">Flow-IPC project: Full implementation reference.</div> |
| 27 | + </td> |
| 28 | + </tr> |
| 29 | + </tbody> |
| 30 | +</table> |
| 31 | +</div> |
| 32 | +<!-- end header part --> |
| 33 | +<!-- Generated by Doxygen 1.9.4 --> |
| 34 | +<script type="text/javascript"> |
| 35 | +/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ |
| 36 | +var searchBox = new SearchBox("searchBox", "search",'Search','.html'); |
| 37 | +/* @license-end */ |
| 38 | +</script> |
| 39 | +<script type="text/javascript" src="menudata.js"></script> |
| 40 | +<script type="text/javascript" src="menu.js"></script> |
| 41 | +<script type="text/javascript"> |
| 42 | +/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ |
| 43 | +$(function() { |
| 44 | + initMenu('',true,false,'search.php','Search'); |
| 45 | + $(document).ready(function() { init_search(); }); |
| 46 | +}); |
| 47 | +/* @license-end */ |
| 48 | +</script> |
| 49 | +<div id="main-nav"></div> |
| 50 | +<!-- window showing the filter options --> |
| 51 | +<div id="MSearchSelectWindow" |
| 52 | + onmouseover="return searchBox.OnSearchSelectShow()" |
| 53 | + onmouseout="return searchBox.OnSearchSelectHide()" |
| 54 | + onkeydown="return searchBox.OnSearchSelectKey(event)"> |
| 55 | +</div> |
| 56 | + |
| 57 | +<!-- iframe showing the search results (closed by default) --> |
| 58 | +<div id="MSearchResultsWindow"> |
| 59 | +<iframe src="javascript:void(0)" frameborder="0" |
| 60 | + name="MSearchResults" id="MSearchResults"> |
| 61 | +</iframe> |
| 62 | +</div> |
| 63 | + |
| 64 | +</div><!-- top --> |
| 65 | +<div><div class="header"> |
| 66 | + <div class="headertitle"><div class="title">(Manual Start) Flow-IPC: Bird's-eye View </div></div> |
| 67 | +</div><!--header--> |
| 68 | +<div class="contents"> |
| 69 | +<div class="textblock"><center><b>MANUAL NAVIGATION:</b> <a class="el" href="api_overview.html">Next Page</a> - <a href="./pages.html"><b>Table of Contents</b></a> - <a class="el" href="namespaceipc.html"><b>Reference</b></a></center><hr /> |
| 70 | +<p ><a class="anchor" id="fig0"></a></p><div class="image"> |
| 71 | +<img src="sessions_and_transport_high_v2.png" alt=""/> |
| 72 | +</div> |
| 73 | +<ul> |
| 74 | +<li>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 <em>channels</em> over which one can transmit <em>messages</em> with a few lines of code.</li> |
| 75 | +<li>On the right – zooming into a single <em>channel</em>; and how it transmits data of various kinds, especially without copying (therefore at high speed).<ul> |
| 76 | +<li>"capnp" stands for <a href="https://capnproto.org/language.html">Cap'n Proto</a>.</li> |
| 77 | +<li>Some readers have said this diagram is too "busy." If that's your impression: Please do not worry about the details. It is a <em>survey</em> of what and how one <em>could</em> transmit via Flow-IPC; different details might appeal to different users.</li> |
| 78 | +<li>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.</li> |
| 79 | +</ul> |
| 80 | +</li> |
| 81 | +</ul> |
| 82 | +<p >We hope a picture is worth a thousand words, but please do scroll down to read a few words anyway.</p> |
| 83 | +<p >If you'd prefer a synopsis with code snippets, right away, try <a class="el" href="api_overview.html">API Overview / Synopses</a>.</p> |
| 84 | +<h2>Executive summary: Why does Flow-IPC exist? </h2> |
| 85 | +<p >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 <a href="https://grpc.io/">gRPC</a>, usually written around <a href="https://protobuf.dev/">Protocol Buffers</a> serialization.) Low-level interprocess communication (<em>IPC</em>) 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.</p> |
| 86 | +<p >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 (<em>capnp</em>) serialization library, which is integrated directly into our shared memory (SHM) system. The Flow-IPC SHM system extends a commercial-grade memory manager (<em>jemalloc</em>, as used by FreeBSD and Meta). Overall, this approach eliminates all memory copying (end-to-end <em>zero copy</em>).</p> |
| 87 | +<p >Flow-IPC features a session-based channel management model. A <em>session</em> 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.</p> |
| 88 | +<p >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.</p> |
| 89 | +<hr /> |
| 90 | +<p >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 <a class="el" href="namespaceipc.html">Reference</a>.)</p> |
| 91 | +<h2>Feature overview: What is Flow-IPC? </h2> |
| 92 | +<p >Flow-IPC:</p><ul> |
| 93 | +<li>is a <b>modern C++</b> library with a concept-based API in the spirit of STL/Boost;</li> |
| 94 | +<li>enables near-zero-latency <b>zero-copy</b> messaging between processes (via behind-the-scenes use of the below SHM solution);</li> |
| 95 | +<li>transmits messages containing binary data, native handles, and/or <b>structured data</b> (defined via <a href="https://capnproto.org/language.html">Cap'n Proto</a>);</li> |
| 96 | +<li>provides a <b>shared memory (SHM)</b> solution<ul> |
| 97 | +<li>with out-of-the-box ability to transmit arbitrarily complex combinations of scalars, <code>struct</code>s, and <b>STL-compliant containers</b> thereof;</li> |
| 98 | +<li>that integrates with <b>commercial-grade memory managers</b> (a/k/a <code>malloc()</code> providers).<ul> |
| 99 | +<li>In particular we integrate with <a href="https://jemalloc.net">jemalloc</a>, a thread-caching memory manager at the core of FreeBSD, Meta, and others.</li> |
| 100 | +</ul> |
| 101 | +</li> |
| 102 | +</ul> |
| 103 | +</li> |
| 104 | +</ul> |
| 105 | +<p >A key feature of Flow-IPC is pain-free setup of process-to-process conversations (<b>sessions</b>), so that users need not worry about coordinating individual shared-resource naming between processes, not to mention kernel-persistent resource cleanup.</p> |
| 106 | +<p >Flow-IPC provides 2 ways to integrate with your applications' event loops. These can be intermixed.</p><ul> |
| 107 | +<li>The <b>async-I/O API</b> automatically starts threads as needed to offload work onto multi-processor cores.</li> |
| 108 | +<li>The <code>sync_io</code> <b>API</b> supplies lighter-weight objects allowing you full control over each application's thread structure, hooking into reactor-style (<code>poll()</code>, <code>epoll_wait()</code>, etc.) or proactor (boost.asio) event loops. As a result context switching is minimized.</li> |
| 109 | +</ul> |
| 110 | +<p >Lastly Flow-IPC supplies <b>lower-level utilities</b> facilitating work with POSIX and SHM-based <b>message queues (MQs)</b> and <b>local (Unix domain) stream sockets</b>.</p> |
| 111 | +<h2>Delving deeper </h2> |
| 112 | +<p >The high-level diagram <a class="el" href="about.html#fig0">above</a> is a pretty good synopsis of the highest-impact features. The following diagram delves deeper, roughly introducing the <em>core</em> layer of <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a>. Then we begin a textual exploration in <a class="el" href="api_overview.html">API Overview / Synopses</a>.</p> |
| 113 | +<div class="image"> |
| 114 | +<img src="1x1.png" alt=""/> |
| 115 | +<div class="caption"> |
| 116 | +Figure 1. IPC channels (core layer); SHM arenas; and your code.</div></div> |
| 117 | + <div class="image"> |
| 118 | +<img src="transport_core_v1.png" alt=""/> |
| 119 | +</div> |
| 120 | +<h2>Future directions of work </h2> |
| 121 | +<p >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.</p><ul> |
| 122 | +<li><b>Networked IPC</b>: 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.</li> |
| 123 | +<li><b>Networked "shared memory" (RDMA)</b>: 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 <em>is</em>, however, <a href="https://en.wikipedia.org/wiki/Remote_direct_memory_access">Remote Direct Memory Access (RDMA)</a>: 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.</li> |
| 124 | +<li><b>Beyond C++</b>: 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.</li> |
| 125 | +<li><b>More architectures</b>: 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.</li> |
| 126 | +</ul> |
| 127 | +<p >We welcome feedback, ideas, and (of course) pull requests of all kinds!</p> |
| 128 | +<hr /> |
| 129 | +<p >Onward!</p> |
| 130 | +<hr /> |
| 131 | +<center><b>MANUAL NAVIGATION:</b> <a class="el" href="api_overview.html">Next Page</a> - <a href="./pages.html"><b>Table of Contents</b></a> - <a class="el" href="namespaceipc.html"><b>Reference</b></a></center> </div></div><!-- contents --> |
| 132 | +</div><!-- PageDoc --> |
| 133 | +<!-- start footer part --> |
| 134 | +<hr class="footer"/><address class="footer"><small> |
| 135 | +Generated on Sat Mar 30 2024 02:06:54 for Flow-IPC by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4 |
| 136 | +</small></address> |
| 137 | +</body> |
| 138 | +</html> |
0 commit comments