Skip to content

Commit cae9b5a

Browse files
ygoldfeldygoldfeld
committed
(manual/README)
1 parent 806c7fd commit cae9b5a

11 files changed

+36
-38
lines changed

‎README.md

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -10,28 +10,26 @@ in the project's main documentation.
1010
corresponding sets of such documentation.
1111
- If you'd prefer to jump into some code right away:
1212
- We estimate the median topic of highest interest to be transmission of structured-data messages, as described
13-
by a [simple schema language, Cap'n Proto](https://capnproto.org). Therefore:
14-
- Take a look at this [synopsis example of transmitting structured Cap'n Proto-described
13+
by a schema language, Cap'n Proto a/k/a [capnp](https://capnproto.org). capnp by itself provides best-in-class
14+
*serialization* but only rudimentary APIs for *transmission* of serialized data. Therefore:
15+
- Take a look at [the synopsis/example of transmitting structured Cap'n Proto-described
1516
messages](https://flow-ipc.github.io/doc/flow-ipc/versions/main/generated/html_public/api_overview.html#api_overview_transport_struc_synopsis)
16-
between processes. (Cap'n Proto -- a/k/a capnp -- by itself provides best-in-class serialization but only
17-
rudimentary transmission of the serialized data.) That's convenient -- more so than capnp alone -- but it
18-
still involves (internally) needing to copy the content of the data into an IPC transport (Unix domain socket,
19-
etc.) and then, again, out of that transport on the receiving side. So, instead of 2 potentially quite
20-
expensive copies:
21-
- We'd like, instead, **end-to-end zero-copy performance and semantics** -- without *any* copying of the data
22-
(which can be huge) at any stage. Setting this up requires shared memory work and is difficult even in
23-
specialized fashion. Flow-IPC, however, makes it extremely easy:
24-
- The above synopsis/example is immediately followed by this
17+
between processes. This shows convenience -- more so than with capnp alone.
18+
- Yet it still involves (behind the scenes) having to *copy the content of the data* into an IPC transport (e.g., Unix
19+
domain socket) and then, *again*, out of that transport into the user memory on the receiving side. We'd like,
20+
instead, **end-to-end zero-copy performance** and semantics. Normally this requires shared memory (SHM) work which
21+
is difficult coding even in specialized scenarios. Flow-IPC, however, makes it very easy...
22+
- ...as shown in this
2523
[explanation](https://flow-ipc.github.io/doc/flow-ipc/versions/main/generated/html_public/api_overview.html#api_overview_transport_struc_zero)
2624
and [code example](https://flow-ipc.github.io/doc/flow-ipc/versions/main/generated/html_public/api_overview.html#api_overview_transport_struc_zero_synopsis).
27-
This shows it takes *two changed lines of code*, when setting up your IPC. The rest of the code remains
28-
the same.
25+
This shows it takes *two changed lines of code*, when setting up. The "meat" of your code remains
26+
unchanged.
2927
- That said, Flow-IPC provides entry points at every layer of operation, both higher and lower than the
30-
above topic/example. It is *not* designed as merely a "black box" of capabilities. E.g.:
28+
above topic/example. Flow-IPC is *not* designed as merely a "black box" of capabilities. E.g.:
3129
- Various lower-level APIs, such as low-level transports (Unix domain sockets, MQs) and SHM operations can be
32-
accessed directly.
30+
accessed directly. You can also plug-in your own.
3331
- By implementing or accessing some of the handful of key concepts, you can customize behaviors at all layers,
34-
including serialization memory backing, additional SHM providers, and native data structures that use raw pointers
32+
including serialization-memory backing, additional SHM providers, and native data structures that use raw pointers
3533
instead of/in addition to STL-compliant containers.
3634
- In general, we feel it is comprehensive and flexible, as well as performance-oriented with an eye to safety. [The API tour page of the Manual](https://flow-ipc.github.io/doc/flow-ipc/versions/main/generated/html_public/api_overview.html) will show you around. [The rest of the guided Manual](https://flow-ipc.github.io/doc/flow-ipc/versions/main/generated/html_public/pages.html) and the @link ::ipc Reference@endlink go deeper.
3735

‎src/doc/manual/c-setup.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page setup Prerequisites and Setup
2121

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

2424
---
2525

@@ -89,6 +89,6 @@ With this setup stuff out of the way we're almost ready to start using Flow-IPC.
8989

9090
---
9191

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

9494
*/

‎src/doc/manual/d-async_loop.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page async_loop Asynchronicity and Integrating with Your Event Loop
2121

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

2424
---
2525

@@ -280,6 +280,6 @@ We're now ready to make Flow-IPC actually do something. Let's move on to @ref s
280280

281281
---
282282

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

285285
*/

‎src/doc/manual/e-session_setup.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page session_setup Sessions: Setting Up an IPC Context
2121

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

2424
---
2525

@@ -291,6 +291,6 @@ Next let's discuss @ref chan_open.
291291

292292
---
293293

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

296296
*/

‎src/doc/manual/f-chan_open.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page chan_open Sessions: Opening Channels
2121

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

2424
---
2525

@@ -407,6 +407,6 @@ Opening channels is the main point of sessions, so we are close to done, as far
407407

408408
---
409409

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

412412
*/

‎src/doc/manual/g-session_app_org.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page session_app_org Sessions: Teardown; Organizing Your Code
2121

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

2424
---
2525

@@ -529,6 +529,6 @@ The next page is: @ref safety_perms.
529529

530530
---
531531

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

534534
*/

‎src/doc/manual/h-safety_perms.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page safety_perms Safety and Permissions
2121

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

2424
---
2525

@@ -146,6 +146,6 @@ The next page is: @ref universes.
146146

147147
---
148148

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

151151
*/

‎src/doc/manual/i-universes.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page universes Multi-split Universes
2121

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

2424
---
2525

@@ -33,6 +33,6 @@ The next page is: @ref chan_struct.
3333

3434
---
3535

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

3838
*/

‎src/doc/manual/j-chan_struct.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page chan_struct Structured Message Transport
2121

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

2424
---
2525

@@ -729,6 +729,6 @@ The next page is: @ref chan_struct_advanced.
729729

730730
---
731731

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

734734
*/

‎src/doc/manual/k-chan_struct_advanced.dox.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page chan_struct_advanced Structured Message Transport: Messages As Long-lived Data Structures / Advanced Topics
2121

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

2424
---
2525

@@ -174,6 +174,6 @@ The next page is: @ref transport_shm.
174174

175175
---
176176

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

179179
*/

‎src/doc/manual/l-transport_shm.dox.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
@page transport_shm Shared Memory: Direct Allocation, Transport
2121

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

2424
---
2525

@@ -455,15 +455,15 @@ The next page is: @ref transport_core.
455455

456456
---
457457

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

460460
*/
461461

462462
/**
463463

464464
@page transport_core Transport Core Layer: Transmitting Unstructured Data
465465

466-
<center>**MANUAL NAVIGATION:** @ref transport_shm "Preceding Page" - [**Table of Contents**](./pages.html)</center>
466+
<center>**MANUAL NAVIGATION:** @ref transport_shm "Preceding Page" - [**Table of Contents**](./pages.html) - @link ::ipc **Reference**@endlink</center>
467467

468468
---
469469

@@ -473,6 +473,6 @@ This page is under construction; it is referred-to but not yet written. However
473473

474474
---
475475

476-
<center>**MANUAL NAVIGATION:** @ref transport_shm "Preceding Page" - [**Table of Contents**](./pages.html)</center>
476+
<center>**MANUAL NAVIGATION:** @ref transport_shm "Preceding Page" - [**Table of Contents**](./pages.html) - @link ::ipc **Reference**@endlink</center>
477477

478478
*/

0 commit comments

Comments
 (0)