1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
//! Long-form documentation for ferrompi.
//!
//! This module embeds the Markdown files from the `docs/` directory directly
//! into rustdoc via `#[doc = include_str!(...)]`. Each sub-module corresponds
//! to one documentation artifact. The same content is available as plain
//! Markdown on GitHub at `docs/` and `docs/adr/`; see [`docs/README.md`] for
//! a navigable index with relative-link support.
//!
//! [`docs/README.md`]: https://github.com/cobre-rs/ferrompi/blob/main/docs/README.md
/// Architecture overview for ferrompi contributors.
///
/// Describes the six-layer stack, handle tables, thread-safety model, C layer
/// scope, FFI/ABI invariants, the generic `MpiDatatype` trait family, and the
/// error handling model.
/// Migration guide from rsmpi to ferrompi.
///
/// Covers the quick-comparison table, a function-for-function API mapping,
/// migration cookbook examples, unsupported features, and API ergonomic
/// differences.
/// MPI implementation compatibility matrix.
///
/// Documents which features are available on MPICH 3.x/4.x, Open MPI 4/5,
/// Intel MPI, and Cray MPI, including known issues and how to report new
/// compatibility data.
/// ADR-0001: Why ferrompi uses a hand-written C wrapper layer.
///
/// Explains the ABI portability problem with `bindgen`, the handle-table
/// pattern, large-count version gating, and the op-trampoline infrastructure.
/// ADR-0002: Handle-table concurrency strategy for the request table.
///
/// Justifies C11 atomic `compare_exchange_strong` over pthread mutex and a
/// lock-free Treiber stack for safe concurrent slot allocation under
/// `MPI_THREAD_MULTIPLE`.
/// ADR-0003: Sealed generic `MpiDatatype` trait family.
///
/// Documents the design of the sealed-trait type family (`MpiDatatype`,
/// `MpiIndexedDatatype`, `BytePermutable`, `AtomicMpiDatatype`) and the
/// `#[repr(i32)]` discriminant ABI contract for `DatatypeTag`.
/// ADR-0004: `PersistentRequest` lifecycle and buffer-lifetime invariants.
///
/// Covers the `*_init` / `start` / `wait` lifecycle, the decision to omit
/// `_c` large-count variants from persistent shims, and the buffer-borrow
/// safety model.
/// ADR-0005: `MPI_Op_create` safety model.
///
/// Seven decisions covering closure storage (per-op static slot table),
/// `Send + Sync + 'static` bounds, `MPI_Op_free`-before-slot-release drop
/// ordering, default commutativity, per-slot baked-index C trampolines, and
/// `catch_unwind + abort` panic handling.