honeycomb_core/cmap/dim2/links/
mod.rs

1mod one;
2mod two;
3
4use fast_stm::atomically_with_err;
5
6use crate::cmap::{CMap2, DartIdType, LinkError};
7use crate::geometry::CoordsFloat;
8use crate::stm::{Transaction, TransactionClosureResult};
9
10/// # **Link operations**
11impl<T: CoordsFloat> CMap2<T> {
12    /// `I`-link operator.
13    ///
14    /// # Description
15    ///
16    /// This operation corresponds to coherently linking two darts via their *β* images. Unlike
17    /// sewing, this does not alter associated attributes. For a thorough explanation of this
18    /// operation, its hypothesis & consequences, refer to the [user guide][UG].
19    ///
20    /// [UG]: https://lihpc-computational-geometry.github.io/honeycomb/user-guide/definitions/sew.html
21    ///
22    /// # Arguments
23    ///
24    /// - `const I: u8` -- Link dimension.
25    /// - `t: &mut Transaction` -- Transaction associated to the operation.
26    /// - `ld: DartIdType` -- First dart ID.
27    /// - `rd: DartIdType` -- Second dart ID.
28    ///
29    /// # Errors
30    ///
31    /// This method should be called in a transactional context. The `Result` is then used to
32    /// validate the transaction; Errors should not be processed manually, only processed via the
33    /// `?` operator. The policy in case of failure can be defined when creating the transaction,
34    /// using `Transaction::with_control`.
35    ///
36    /// # Panics
37    ///
38    /// The method may panic if:
39    /// - `I >= 3` or `I == 0`,
40    /// - the two darts are not `I`-linkable.
41    pub fn link_tx<const I: u8>(
42        &self,
43        t: &mut Transaction,
44        ld: DartIdType,
45        rd: DartIdType,
46    ) -> TransactionClosureResult<(), LinkError> {
47        // these assertions + match on a const are optimized away
48        assert!(I < 3);
49        assert_ne!(I, 0);
50        match I {
51            1 => self.one_link_tx(t, ld, rd),
52            2 => self.two_link_tx(t, ld, rd),
53            _ => unreachable!(),
54        }
55    }
56
57    /// `I`-unlink operator.
58    ///
59    /// # Description
60    ///
61    /// This operation corresponds to unlinking two darts by resetting their *β* images. Unlike
62    /// unsewing, this does not alter associated attributes. For a thorough explanation of this
63    /// operation, its hypothesis & consequences, refer to the [user guide][UG].
64    ///
65    /// [UG]: https://lihpc-computational-geometry.github.io/honeycomb/user-guide/definitions/sew.html
66    ///
67    /// # Arguments
68    ///
69    /// - `const I: u8` -- Unlink dimension.
70    /// - `t: &mut Transaction` -- Transaction associated to the operation.
71    /// - `ld: DartIdType` -- First dart ID.
72    ///
73    /// The second dart ID is fetched using `I` and `ld`.
74    ///
75    /// # Errors
76    ///
77    /// This method should be called in a transactional context. The `Result` is then used to
78    /// validate the transaction; Errors should not be processed manually, only processed via the
79    /// `?` operator. The policy in case of failure can be defined when creating the transaction,
80    /// using `Transaction::with_control`.
81    ///
82    /// # Panics
83    ///
84    /// The method may panic if:
85    /// - `I >= 3` or `I == 0`,
86    /// - `ld` is already `I`-free.
87    pub fn unlink_tx<const I: u8>(
88        &self,
89        t: &mut Transaction,
90        ld: DartIdType,
91    ) -> TransactionClosureResult<(), LinkError> {
92        // these assertions + match on a const are optimized away
93        assert!(I < 3);
94        assert_ne!(I, 0);
95        match I {
96            1 => self.one_unlink_tx(t, ld),
97            2 => self.two_unlink_tx(t, ld),
98            _ => unreachable!(),
99        }
100    }
101
102    #[allow(clippy::missing_errors_doc, clippy::missing_panics_doc)]
103    /// `I`-link operator.
104    ///
105    /// This variant is equivalent to [`link`][Self::link], but internally uses a transaction that
106    /// will be retried until validated.
107    pub fn link<const I: u8>(&self, ld: DartIdType, rd: DartIdType) -> Result<(), LinkError> {
108        // these assertions + match on a const are optimized away
109        assert!(I < 3);
110        assert_ne!(I, 0);
111        match I {
112            1 => atomically_with_err(|t| self.one_link_tx(t, ld, rd)),
113            2 => atomically_with_err(|t| self.two_link_tx(t, ld, rd)),
114            _ => unreachable!(),
115        }
116    }
117
118    #[allow(clippy::missing_errors_doc, clippy::missing_panics_doc)]
119    /// # `I`-unlink operator.
120    ///
121    /// This variant is equivalent to [`unlink`][Self::unlink], but internally uses a transaction
122    /// that will be retried until validated.
123    pub fn unlink<const I: u8>(&self, ld: DartIdType) -> Result<(), LinkError> {
124        // these assertions + match on a const are optimized away
125        assert!(I < 3);
126        assert_ne!(I, 0);
127        match I {
128            1 => atomically_with_err(|t| self.one_unlink_tx(t, ld)),
129            2 => atomically_with_err(|t| self.two_unlink_tx(t, ld)),
130            _ => unreachable!(),
131        }
132    }
133}
honeycomb_core/cmap/dim2/links/mod.rs

honeycomb_core/cmap/dim2/links/
mod.rs
