Skip to main content

tenferro_mpi/
backend.rs

1//! The MPI primitives the transport protocol needs, and the two backend bindings.
2
3use crate::wire::Tag;
4
5/// The MPI operations one transport call performs.
6///
7/// The protocol itself lives in [`crate::engine`] and is written once against this
8/// trait, so a second MPI binding only supplies these four operations.
9///
10/// Implementations borrow the caller's communicator through `Peer`; nothing here
11/// initializes, finalizes or duplicates a communicator.
12///
13/// # Examples
14///
15/// ```
16/// use tenferro_mpi::MpiBackend;
17///
18/// fn is_self<B: MpiBackend>(peer: B::Peer<'_>) -> bool {
19///     B::is_self(peer)
20/// }
21/// ```
22pub trait MpiBackend {
23    /// A destination or source rank handle, borrowed from the caller's communicator.
24    type Peer<'a>: Copy;
25
26    /// A message that has been probed and must be received exactly once.
27    type Probed;
28
29    /// Whether `peer` is the calling rank.
30    fn is_self(peer: Self::Peer<'_>) -> bool;
31
32    /// Blocking send of `buffer` as bytes.
33    fn send_bytes(&self, to: Self::Peer<'_>, tag: Tag, buffer: &[u8]);
34
35    /// Blocking probe: consume the next message from `from` on `tag` and report its
36    /// byte length.
37    ///
38    /// Probing before receiving is what keeps a non-conforming frame a typed error
39    /// instead of a fatal MPI truncation.
40    fn probe(&self, from: Self::Peer<'_>, tag: Tag) -> (Self::Probed, i64);
41
42    /// Receive a probed message, returning the byte count it carried.
43    fn receive_probed(&self, probed: Self::Probed, buffer: &mut [u8]) -> i64;
44}
45
46#[cfg(feature = "system")]
47mod system {
48    use mpi::point_to_point::Message;
49    use mpi::topology::Process;
50    use mpi::traits::{Destination, Equivalence, Source};
51
52    use super::MpiBackend;
53    use crate::wire::Tag;
54
55    /// The `system` backend: rsmpi-rt's bindgen `mpi-sys-backend` (crates.io
56    /// rsmpi-sys 0.2.4) against system MPI headers and libclang.
57    ///
58    /// # Examples
59    ///
60    /// ```
61    /// use tenferro_mpi::System;
62    ///
63    /// let backend = System;
64    /// assert_eq!(format!("{backend:?}"), "System");
65    /// ```
66    #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
67    pub struct System;
68
69    impl MpiBackend for System {
70        type Peer<'a> = Process<'a>;
71        type Probed = Message;
72
73        fn is_self(peer: Self::Peer<'_>) -> bool {
74            peer.is_self()
75        }
76
77        fn send_bytes(&self, to: Self::Peer<'_>, tag: Tag, buffer: &[u8]) {
78            to.send_with_tag(buffer, tag);
79        }
80
81        fn probe(&self, from: Self::Peer<'_>, tag: Tag) -> (Self::Probed, i64) {
82            let (message, status) = from.matched_probe_with_tag(tag);
83            (message, i64::from(status.count(u8::equivalent_datatype())))
84        }
85
86        fn receive_probed(&self, probed: Self::Probed, buffer: &mut [u8]) -> i64 {
87            let status = probed.matched_receive_into(buffer);
88            i64::from(status.count(u8::equivalent_datatype()))
89        }
90    }
91}
92
93#[cfg(feature = "runtime")]
94mod runtime {
95    use mpi::point_to_point::Message;
96    use mpi::topology::Process;
97    use mpi::traits::{Destination, Equivalence, Source};
98
99    use super::MpiBackend;
100    use crate::wire::Tag;
101
102    /// The `runtime` backend: rsmpi-rt's MPIABI `mpi-rt-sys-backend` (crates.io
103    /// mpi-rt-sys 0.1.0), which loads MPI at run time.
104    ///
105    /// # Examples
106    ///
107    /// ```
108    /// use tenferro_mpi::Rt;
109    ///
110    /// let backend = Rt;
111    /// assert_eq!(format!("{backend:?}"), "Rt");
112    /// ```
113    #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
114    pub struct Rt;
115
116    impl MpiBackend for Rt {
117        type Peer<'a> = Process<'a>;
118        type Probed = Message;
119
120        fn is_self(peer: Self::Peer<'_>) -> bool {
121            peer.is_self()
122        }
123
124        fn send_bytes(&self, to: Self::Peer<'_>, tag: Tag, buffer: &[u8]) {
125            to.send_with_tag(buffer, tag);
126        }
127
128        fn probe(&self, from: Self::Peer<'_>, tag: Tag) -> (Self::Probed, i64) {
129            let (message, status) = from.matched_probe_with_tag(tag);
130            (message, i64::from(status.count(u8::equivalent_datatype())))
131        }
132
133        fn receive_probed(&self, probed: Self::Probed, buffer: &mut [u8]) -> i64 {
134            let status = probed.matched_receive_into(buffer);
135            i64::from(status.count(u8::equivalent_datatype()))
136        }
137    }
138}
139
140#[cfg(feature = "runtime")]
141pub use runtime::Rt;
142#[cfg(feature = "system")]
143pub use system::System;