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