mpi_rma/lib.rs
1//! Typed, safe MPI one-sided communication (RMA) for Rust, on top of
2//! [rsmpi](https://docs.rs/mpi).
3//!
4//! rsmpi does not expose RMA windows. This crate contains the raw RMA calls,
5//! extends every rsmpi communicator through [`CommunicatorRmaExt`], and builds
6//! fixed-slot [`Ring`] transport on those windows.
7//!
8//! [`Ring::safe`] provides backpressure with a cumulative-acknowledgement
9//! gate. [`Ring::raw`] never blocks and reports overwritten messages instead.
10//! Polling reads local memory; each safe [`Ring::ack`] call uses one atomic
11//! MPI operation.
12//!
13//! ```no_run
14//! use mpi::topology::Communicator;
15//! use mpi_rma::Ring;
16//!
17//! # let (universe, _) = mpi::initialize_with_threading(mpi::Threading::Multiple).unwrap();
18//! let world = universe.world();
19//! // One lane from rank 0 to rank 1: 8 slots of 64 KiB each.
20//! let ring = Ring::safe(&world, &[(0, 1, 8, 64 * 1024)]).unwrap();
21//! if world.rank() == 0 {
22//! ring.send(1, b"hello").unwrap();
23//! } else if world.rank() == 1 {
24//! 'receive: loop {
25//! for message in ring.poll().unwrap() {
26//! ring.ack(message.origin, message.sequence).unwrap();
27//! break 'receive;
28//! }
29//! std::thread::yield_now();
30//! }
31//! }
32//! ring.close().unwrap();
33//! ```
34//!
35//! See `design.md` for the slot layout, sequencing rules, and the
36//! acknowledge-gating model behind the ring transport, and `BENCHMARKS.md`
37//! for measured throughput and latency against MPI point-to-point.
38
39mod error;
40mod ring;
41mod window;
42
43pub use error::Error;
44pub use ring::{Message, Ring};
45pub use window::{CommunicatorRmaExt, MemoryModel, RmaElement, Window};
46
47/// rsmpi-style trait prelude. Importing this extends the original
48/// communicator types in place; no communicator wrapper is involved.
49pub mod traits {
50 pub use crate::CommunicatorRmaExt;
51}