Skip to content

Commit b2f74b9

Browse files
committed
Adjust README tone
1 parent 09aff0d commit b2f74b9

File tree

1 file changed

+13
-14
lines changed

1 file changed

+13
-14
lines changed

README.md

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ structure multi-process workflows.
5454
* **Header-only distribution** - integrate the library by adding the headers to a
5555
project; no separate build step or binaries are necessary.
5656
* **No RTTI required** - type ids are derived from compile-time signatures (or
57-
explicit ids if you choose to pin them).
57+
explicit ids when pinned).
5858
* **Cross-platform design** - shared-memory transport on Linux, macOS, Windows, and FreeBSD.
5959
* **Opt-in crash recovery** - mark critical workers with `sintra::enable_recovery()` so
6060
the coordinator automatically respawns them after an unexpected exit.
@@ -128,9 +128,9 @@ For a Qt widget example that forwards Qt signals through sintra, see `example/qt
128128
## Optional explicit type ids
129129
130130
Most users do not need explicit type ids as long as every process is built with the same
131-
toolchain and flags. If you mix toolchains or want to remove any doubt about type id
132-
stability, you can pin ids explicitly for both transceivers and messages. Keep the
133-
ids unique and consistent across every process in the swarm.
131+
toolchain and flags. When toolchains are mixed or there is a need to remove any doubt
132+
about type id stability, ids can be pinned explicitly for both transceivers and messages.
133+
The ids must remain unique and consistent across every process in the swarm.
134134
135135
```cpp
136136
struct Explicit_bus : sintra::Derived_transceiver<Explicit_bus>
@@ -162,11 +162,11 @@ Sintra uses **dedicated reader threads** to process incoming messages from share
162162

163163
### Barrier Semantics
164164

165-
`sintra::barrier()` coordinates progress across processes and comes in three flavors that trade off strength for cost. The template defaults to `delivery_fence_t`, so a plain `barrier("name")` is already stronger than a bare rendezvous. Choose the lightest-weight barrier whose guarantees match the code's requirements:
165+
`sintra::barrier()` coordinates progress across processes and comes in three flavors that trade off strength for cost. The template defaults to `delivery_fence_t`, so a plain `barrier("name")` is already stronger than a bare rendezvous. The lightest-weight barrier whose guarantees match the code's requirements is preferred:
166166

167-
* **Rendezvous barriers** (`barrier<sintra::rendezvous_t>(name)`) simply ensure that every participant has reached the synchronization point. Messages published before the barrier might still be in flight or waiting to be handled, so use this mode when only aligned phase progression is needed-for example, coordinating the simultaneous start of a workload whose logic does not depend on the effects of earlier messages.
168-
* **Delivery-fence barriers** (`barrier(name)` or `barrier<sintra::delivery_fence_t>(name)`) guarantee that all pre-barrier messages have been pulled off the shared-memory rings by each process’s reader thread and are queued locally for handling, though the handlers may still be running. Reach for the default delivery fence when the next step requires the complete set of incoming work to be staged, such as inspecting an inbox before taking action.
169-
* **Processing-fence barriers** (`barrier<sintra::processing_fence_t>(name)`) wait until every handler (and any continuations) for messages published before the barrier has finished executing. Choose this mode when subsequent logic must observe the completed side effects-for instance, reading shared state that earlier handlers updated or applying a configuration change only after all peers processed preparatory updates.
167+
* **Rendezvous barriers** (`barrier<sintra::rendezvous_t>(name)`) simply ensure that every participant has reached the synchronization point. Messages published before the barrier might still be in flight or waiting to be handled, so this mode is appropriate when only aligned phase progression is needed-for example, coordinating the simultaneous start of a workload whose logic does not depend on the effects of earlier messages.
168+
* **Delivery-fence barriers** (`barrier(name)` or `barrier<sintra::delivery_fence_t>(name)`) guarantee that all pre-barrier messages have been pulled off the shared-memory rings by each process’s reader thread and are queued locally for handling, though the handlers may still be running. The default delivery fence is suitable when the next step requires the complete set of incoming work to be staged, such as inspecting an inbox before taking action.
169+
* **Processing-fence barriers** (`barrier<sintra::processing_fence_t>(name)`) wait until every handler (and any continuations) for messages published before the barrier has finished executing. This mode is appropriate when subsequent logic must observe the completed side effects-for instance, reading shared state that earlier handlers updated or applying a configuration change only after all peers processed preparatory updates.
170170

171171
Delivery fences cost the same as rendezvous plus a short wait for readers to catch up. Processing fences add a single control message per process and an extra rendezvous to allow deterministic observation of handler side effects.
172172

@@ -178,21 +178,20 @@ sintra::barrier("phase-1"); // delivery fence
178178
sintra::barrier<sintra::processing_fence_t>("apply-updates");
179179
```
180180
181-
Processing fences are safe to call from any thread, including handlers themselves: reader threads continue draining queued work and post-handlers while the fence waits, so invoking a fence from within a handler keeps the system making progress. When coordination between threads inside the same process is also required, combine Sintra barriers with standard threading primitives.
181+
Processing fences are safe to call from any thread, including handlers themselves: reader threads continue draining queued work and post-handlers while the fence waits, so invoking a fence from within a handler keeps the system making progress. When coordination between threads inside the same process is also required, Sintra barriers typically pair with standard threading primitives.
182182
183183
## Getting started
184184
185-
1. Add the `include/` directory to the project's include path.
186-
2. Ensure that a C++17 compliant compiler is used (GCC, Clang, or MSVC are supported).
187-
3. Explore the `example/` directory to see how to set up signal buses, channels, and
188-
remote call endpoints.
185+
1. The `include/` directory must be on the project's include path.
186+
2. A C++17 compliant compiler is required (GCC, Clang, or MSVC are supported).
187+
3. The `example/` directory contains signal bus, channel, and remote call samples.
189188
190189
Because everything ships as headers, Sintra works well in monorepos or projects that
191190
prefer vendoring dependencies as git submodules or fetching them during configuration.
192191
193192
## Platform requirements
194193
195-
* **macOS** - Sintra always uses `os_sync_wait_on_address` for its interprocess semaphore implementation. The build fails if `<os/os_sync_wait_on_address.h>` or `<os/clock.h>` is missing, so ensure the runner has macOS 15.0 or newer with the Command Line Tools for Xcode 15 (or newer) installed (the full Xcode IDE is not required). No legacy semaphore fallback is provided or supported.
194+
* **macOS** - Sintra always uses `os_sync_wait_on_address` for its interprocess semaphore implementation. The build fails if `<os/os_sync_wait_on_address.h>` or `<os/clock.h>` is missing, so runners should use macOS 15.0 or newer with the Command Line Tools for Xcode 15 (or newer) installed (the full Xcode IDE is not required). No legacy semaphore fallback is provided or supported.
196195
197196
## Tests and continuous integration
198197

0 commit comments

Comments
 (0)