1#[cfg(feature = "tokio")]
4use std::collections::HashSet;
5use std::sync::{Arc, Mutex};
6
7#[cfg(feature = "tokio")]
8use orbit_core::shm::try_hold_watcher;
9use orbit_core::shm::{
10 LaneHold, ShmRegion, ring_segment_name, try_hold_lane, wait_lane_free,
11};
12
13use super::{Error, Inbox, LinkSpec, Reclaimed, Result};
14
15pub struct LinkSegment {
17 region: ShmRegion,
18 inbox: Inbox,
19 name: String,
20 fleet_name: String,
21 spec: LinkSpec,
22 group: Option<orbit_core::shm::GroupAccess>,
23 reclaimed: Mutex<Vec<Reclaimed>>,
25 #[cfg(feature = "tokio")]
26 receivers: Mutex<HashSet<usize>>,
27 #[cfg(feature = "tokio")]
29 producer_bell: Mutex<Option<Arc<tokio::net::UnixDatagram>>>,
30}
31
32pub struct Joined {
42 pub lane: usize,
43 pub hold: LaneHold,
44 pub reclaimed: Vec<Reclaimed>,
45 segment: String,
46 epoch: u64,
47}
48
49impl Joined {
50 pub fn epoch(&self) -> u64 {
52 self.epoch
53 }
54
55 pub(crate) fn belongs_to(
56 &self,
57 segment: &LinkSegment,
58 ) -> bool {
59 self.segment == segment.name
60 && segment.inbox.lane_epoch(self.lane).ok() == Some(self.epoch)
61 }
62}
63
64impl LinkSegment {
65 pub fn open(
67 name: &str,
68 spec: LinkSpec,
69 ) -> Result<Self> {
70 Self::open_inner(name, spec, None, true)?
71 .ok_or(Error::Malformed("a created Link inbox was not opened"))
72 }
73
74 pub fn adopt(
80 name: &str,
81 inbox_kind: u8,
82 stream_kind: u8,
83 ) -> Result<Option<Self>> {
84 validate_name(name)?;
85 let segment_name = ring_segment_name(name, inbox_kind);
86 let Some((region, lock)) = ShmRegion::open_existing_locked(
87 &segment_name,
88 size_of::<crate::inbox::TableHeader>(),
89 )?
90 else {
91 return Ok(None);
92 };
93 let (fleet_capacity, inbox) =
96 unsafe { Inbox::persisted_shape(region.as_ptr()) }?;
97 drop(lock);
98 drop(region);
99 let Some((stream_fleet, streams)) =
100 orbit_stream::Streams::persisted_spec(name, stream_kind)?
101 else {
102 return Ok(None);
103 };
104 if usize::from(stream_fleet) != fleet_capacity {
105 return Err(Error::Malformed(
106 "link stream fleet capacity differs from its inbox",
107 ));
108 }
109 let fleet_capacity = u16::try_from(fleet_capacity).map_err(|_| {
110 Error::Malformed("inbox fleet capacity must fit a nonzero u16")
111 })?;
112 let spec = LinkSpec::new(fleet_capacity, inbox_kind, inbox, streams);
113 Self::open_inner(name, spec, None, false)
114 }
115
116 pub fn open_group(
119 name: &str,
120 spec: LinkSpec,
121 access: orbit_core::shm::GroupAccess,
122 ) -> Result<Self> {
123 Self::open_inner(name, spec, Some(access), true)?
124 .ok_or(Error::Malformed("a created Link inbox was not opened"))
125 }
126
127 fn open_inner(
129 name: &str,
130 spec: LinkSpec,
131 group: Option<orbit_core::shm::GroupAccess>,
132 create: bool,
133 ) -> Result<Option<Self>> {
134 spec.validate()?;
135 let segment_name = if let Some(access) = &group {
136 validate_name(name)?;
137 let segment = access.segment_name(name, spec.inbox_kind);
138 crate::bell::Bell::validate_group_address(
139 access,
140 &segment,
141 usize::from(spec.fleet_capacity - 1),
142 )
143 .map_err(Error::Io)?;
144 access
145 .prepare_locks(&segment, 3 * usize::from(spec.fleet_capacity))
146 .map_err(Error::Io)?;
147 orbit_stream::Streams::prepare_group(
150 name,
151 spec.fleet_capacity,
152 spec.streams,
153 access.clone(),
154 )?;
155 segment
156 } else {
157 check_name(name, spec)?;
158 ring_segment_name(name, spec.inbox_kind)
159 };
160 let bytes = spec.inbox_segment_bytes();
161 let (region, lock) = match &group {
162 Some(access) => access.open_region(&segment_name, bytes)?,
163 None if create => {
164 ShmRegion::open_or_create_locked(&segment_name, bytes)?
165 }
166 None => {
167 match ShmRegion::open_existing_locked(&segment_name, bytes)? {
168 Some(opened) => opened,
169 None => return Ok(None),
170 }
171 }
172 };
173 let mut inbox = if region.created() {
174 unsafe {
175 Inbox::initialize(
176 region.as_ptr(),
177 spec.fleet_capacity as usize,
178 spec.inbox,
179 )?
180 }
181 } else {
182 unsafe {
183 Inbox::attach(
184 region.as_ptr(),
185 spec.fleet_capacity as usize,
186 spec.inbox,
187 )?
188 }
189 };
190 inbox.install_bell_with_group(&segment_name, group.clone())?;
191 let mut segment = Self {
192 region,
193 inbox,
194 name: segment_name,
195 fleet_name: name.to_owned(),
196 spec,
197 group,
198 reclaimed: Mutex::new(Vec::new()),
199 #[cfg(feature = "tokio")]
200 receivers: Mutex::new(HashSet::new()),
201 #[cfg(feature = "tokio")]
202 producer_bell: Mutex::new(None),
203 };
204 if let Err(error) = segment.register_producer() {
205 if !matches!(error, Error::InboxFull) {
206 return Err(error);
207 }
208 let reclaimed = segment.recover_abandoned()?;
212 *segment.reclaimed.get_mut().map_err(|_| {
213 Error::Malformed("Link recovery observations are poisoned")
214 })? = reclaimed;
215 segment.register_producer()?;
216 }
217 drop(lock);
218 if segment.region.created() && segment.group.is_none() {
219 segment.inbox.ring_adopter();
220 }
221 Ok(Some(segment))
222 }
223
224 #[cfg(feature = "tokio")]
235 pub async fn adopt_when_created(
236 name: &str,
237 inbox_kind: u8,
238 stream_kind: u8,
239 ) -> Result<Self> {
240 validate_name(name)?;
241 let segment_name = ring_segment_name(name, inbox_kind);
242 let _hold = orbit_core::shm::try_hold_adopter(&segment_name)
243 .map_err(Error::Io)?
244 .ok_or(Error::NoWatcher)?;
245 let bell = crate::bell::Bell::with_group(&segment_name, None, 0)
246 .map_err(Error::Io)?;
247 let socket = tokio::net::UnixDatagram::from_std(
248 bell.bind(crate::bell::Doorbell::Adopter).map_err(Error::Io)?,
249 )
250 .map_err(Error::Io)?;
251 struct Unbind(crate::bell::Bell);
252 impl Drop for Unbind {
253 fn drop(&mut self) {
254 self.0.unbind(crate::bell::Doorbell::Adopter);
255 }
256 }
257 let _unbind = Unbind(bell);
258 loop {
259 if let Some(segment) = Self::adopt(name, inbox_kind, stream_kind)? {
260 return Ok(segment);
261 }
262 socket.readable().await.map_err(Error::Io)?;
263 let mut scratch = [0u8; 64];
264 while socket.try_recv(&mut scratch).is_ok() {}
265 }
266 }
267
268 fn register_producer(&mut self) -> Result<()> {
269 let lanes = usize::from(self.spec.fleet_capacity);
271 let name = &self.name;
272 let group = &self.group;
273 self.inbox.register_producer(|index| {
274 match group {
275 Some(access) => access.try_hold_lane(name, lanes + index),
276 None => try_hold_lane(name, lanes + index),
277 }
278 .map_err(Error::Io)
279 })
280 }
281
282 pub fn join(
286 &self,
287 service: &str,
288 role: &str,
289 incarnation: u64,
290 ) -> Result<Joined> {
291 self.join_with_capacity(service, role, incarnation, None)
292 }
293
294 pub fn join_with_capacity(
295 &self,
296 service: &str,
297 role: &str,
298 incarnation: u64,
299 capacity: Option<usize>,
300 ) -> Result<Joined> {
301 let recovered = self.recover_abandoned()?;
302 let (lane, hold) = self.inbox.join_with_capacity(
303 service,
304 role,
305 incarnation,
306 capacity,
307 |lane| {
308 let Some(hold) = self.hold(lane)? else { return Ok(None) };
309 if let Some((_, previous)) = self.inbox.last_owner(lane)? {
312 self.recover_streams(lane, previous)?;
313 }
314 Ok(Some(hold))
315 },
316 )?;
317 let mut reclaimed =
318 std::mem::take(&mut *self.reclaimed.lock().map_err(|_| {
319 Error::Malformed("Link recovery observations are poisoned")
320 })?);
321 for gone in recovered {
322 if !reclaimed.contains(&gone) {
323 reclaimed.push(gone);
324 }
325 }
326 let epoch = self.inbox.lane_epoch(lane)?;
327 Ok(Joined { lane, hold, reclaimed, segment: self.name.clone(), epoch })
328 }
329
330 fn recover_abandoned(&self) -> Result<Vec<Reclaimed>> {
331 self.recover_producers(None)?;
332 let mut reclaimed = Vec::new();
333 for lane in 0..self.inbox.lanes() {
334 if let Some(gone) = self.recover_lane(lane, |gone| {
335 self.recover_streams(gone.lane, gone.incarnation)
336 })? {
337 reclaimed.push(gone);
338 }
339 }
340 Ok(reclaimed)
341 }
342
343 fn recover_streams(
344 &self,
345 lane: usize,
346 incarnation: u64,
347 ) -> Result<()> {
348 if let Some(access) = &self.group {
349 return orbit_stream::Streams::node_dead_in_group(
350 &self.fleet_name,
351 self.spec.fleet_capacity,
352 self.spec.streams,
353 orbit_core::NodeId::new(lane as u16),
354 orbit_stream::Incarnation::new(incarnation),
355 access.clone(),
356 )
357 .map_err(Error::Stream);
358 }
359 orbit_stream::Streams::node_dead_in_shm(
360 &self.fleet_name,
361 self.spec.fleet_capacity,
362 self.spec.streams,
363 orbit_core::NodeId::new(lane as u16),
364 orbit_stream::Incarnation::new(incarnation),
365 )
366 .map(|_| ())
367 .map_err(Error::Stream)
368 }
369
370 pub fn reclaim_if_gone(
380 &self,
381 lane: usize,
382 ) -> Result<Option<Reclaimed>> {
383 self.reclaim_if_gone_with(lane, |_| {})
384 }
385
386 pub fn reclaim_if_gone_with(
389 &self,
390 lane: usize,
391 recover: impl FnOnce(&Reclaimed),
392 ) -> Result<Option<Reclaimed>> {
393 self.recover_lane(lane, |gone| {
394 recover(gone);
395 Ok(())
396 })
397 }
398
399 fn recover_lane(
400 &self,
401 lane: usize,
402 recover: impl FnOnce(&Reclaimed) -> Result<()>,
403 ) -> Result<Option<Reclaimed>> {
404 if self.inbox.consumers(lane)? == 0 && self.inbox.depth(lane)? == 0 {
405 return Ok(None);
406 }
407 match self.hold(lane)? {
408 Some(_gone) => {
409 let gone = match self.inbox.reclaim(lane)? {
410 Some(gone) => Some(gone),
411 None => self.inbox.last_owner(lane)?.map(
412 |(pid, incarnation)| Reclaimed {
413 lane,
414 pid,
415 incarnation,
416 },
417 ),
418 };
419 if let Some(gone) = &gone {
420 recover(gone)?;
421 }
422 self.inbox.retire_lane(lane)?;
426 Ok(gone)
427 }
428 None => Ok(None),
429 }
430 }
431
432 pub fn reclaim_process(
437 &self,
438 pid: u32,
439 incarnation: u64,
440 mut recover: impl FnMut(&Reclaimed),
441 ) -> Result<Vec<Reclaimed>> {
442 self.recover_producers(Some(pid))?;
443 let mut reclaimed = Vec::new();
444 for lane in 0..self.inbox.lanes() {
445 if self.inbox.last_owner(lane)? != Some((pid, incarnation)) {
446 continue;
447 }
448 let Some(_hold) = self.hold(lane)? else { continue };
449 if self.inbox.last_owner(lane)? != Some((pid, incarnation)) {
450 continue;
451 }
452 if self.inbox.consumers(lane)? != 0 {
453 self.inbox.release_lane(lane)?;
454 }
455 let gone = Reclaimed { lane, pid, incarnation };
456 recover(&gone);
457 self.inbox.retire_lane(lane)?;
458 reclaimed.push(gone);
459 }
460 Ok(reclaimed)
461 }
462
463 pub fn wait_lane_released(
468 &self,
469 lane: usize,
470 pid: u32,
471 incarnation: u64,
472 ) -> Result<()> {
473 if self.inbox.last_owner(lane)? != Some((pid, incarnation)) {
474 return Ok(());
475 }
476 match &self.group {
477 Some(access) => access.wait_lane_free(&self.name, lane),
478 None => wait_lane_free(&self.name, lane),
479 }
480 .map_err(Error::Io)
481 }
482
483 pub fn recover_producers(
486 &self,
487 pid: Option<u32>,
488 ) -> Result<()> {
489 self.inbox.recover_producers(pid, |index| {
490 self.hold(self.inbox.lanes() + index)
491 })
492 }
493
494 fn hold(
495 &self,
496 lane: usize,
497 ) -> Result<Option<LaneHold>> {
498 match &self.group {
499 Some(access) => access.try_hold_lane(&self.name, lane),
500 None => try_hold_lane(&self.name, lane),
501 }
502 .map_err(Error::Io)
503 }
504
505 pub fn inbox(&self) -> &Inbox {
506 &self.inbox
507 }
508
509 #[cfg(feature = "tokio")]
516 pub fn receiver(
517 self: &Arc<Self>,
518 lane: usize,
519 ) -> Result<crate::InboxReceiver> {
520 self.inbox.wait_word(lane)?;
521 let mut held = self.receivers.lock().map_err(|_| {
522 Error::Malformed(
523 "the process-local inbox receiver registry is poisoned",
524 )
525 })?;
526 if !held.insert(lane) {
527 return Err(Error::Malformed(
528 "this process already receives the inbox lane",
529 ));
530 }
531 drop(held);
532 match crate::InboxReceiver::bind(Arc::clone(self), lane) {
533 Ok(receiver) => Ok(receiver),
534 Err(error) => {
535 self.release_receiver(lane);
536 Err(error)
537 }
538 }
539 }
540
541 #[cfg(feature = "tokio")]
551 pub fn watch(
552 self: &Arc<Self>,
553 role: &str,
554 ) -> Result<crate::DirectoryWatcher> {
555 for slot in 0..self.inbox.lanes() {
556 let Some(hold) = match &self.group {
557 Some(access) => access.try_hold_watcher(&self.name, slot),
558 None => try_hold_watcher(&self.name, slot),
559 }
560 .map_err(Error::Io)?
561 else {
562 continue;
563 };
564 return crate::DirectoryWatcher::bind(
565 Arc::clone(self),
566 slot,
567 role,
568 hold,
569 );
570 }
571 Err(Error::NoWatcher)
572 }
573
574 #[cfg(feature = "tokio")]
583 pub async fn record_released(&self) -> Result<()> {
584 let socket = {
585 let mut bell = self.producer_bell.lock().map_err(|_| {
586 Error::Malformed("Link producer bell is poisoned")
587 })?;
588 match &*bell {
589 Some(socket) => Arc::clone(socket),
590 None => {
591 let socket = Arc::new(self.inbox.bind_producer()?);
592 *bell = Some(Arc::clone(&socket));
593 socket
594 }
595 }
596 };
597 let mut scratch = [0u8; 64];
599 while socket.try_recv(&mut scratch).is_ok() {}
600 if !self.inbox.wait_for_record()? {
601 return Ok(());
602 }
603 socket.readable().await.map_err(Error::Io)?;
604 while socket.try_recv(&mut scratch).is_ok() {}
605 Ok(())
606 }
607
608 #[cfg(feature = "tokio")]
609 pub(crate) fn release_receiver(
610 &self,
611 lane: usize,
612 ) {
613 if let Ok(mut held) = self.receivers.lock() {
614 held.remove(&lane);
615 }
616 }
617
618 pub fn spec(&self) -> LinkSpec {
619 self.spec
620 }
621
622 pub fn bodies(
624 &self,
625 lane: usize,
626 incarnation: u64,
627 ) -> Result<super::LinkBodies> {
628 match &self.group {
629 Some(access) => super::LinkBodies::for_group(
630 &self.fleet_name,
631 lane,
632 incarnation,
633 self.spec,
634 access.clone(),
635 ),
636 None => {
637 let bodies = super::LinkBodies::for_name(
638 &self.fleet_name,
639 lane,
640 incarnation,
641 self.spec,
642 )?;
643 self.inbox.ring_adopter();
645 Ok(bodies)
646 }
647 }
648 }
649
650 pub(crate) fn open_control_region(
651 &self,
652 kind: u8,
653 size: usize,
654 ) -> Result<(ShmRegion, orbit_core::shm::ShmRegionLock)> {
655 if let Some(access) = &self.group {
656 let name = access.segment_name(&self.fleet_name, kind);
657 return access.open_region(&name, size).map_err(Error::Io);
658 }
659 ShmRegion::open_or_create_locked(
660 &ring_segment_name(&self.fleet_name, kind),
661 size,
662 )
663 .map_err(Error::Io)
664 }
665
666 pub(crate) fn lock_control_region(
667 &self,
668 kind: u8,
669 region: &ShmRegion,
670 ) -> Result<orbit_core::shm::ShmRegionLock> {
671 if self.group.is_some() {
672 let (_, lock) = self.open_control_region(kind, region.len())?;
673 return Ok(lock);
674 }
675 region.lock_exclusive().map_err(Error::Io)
676 }
677
678 pub(crate) fn unlink_control_region(
679 &self,
680 region: &ShmRegion,
681 ) -> Result<()> {
682 match &self.group {
683 Some(access) => access.unlink_region(region),
684 None => region.unlink(),
685 }
686 .map_err(Error::Io)
687 }
688
689 pub fn created(&self) -> bool {
690 self.region.created()
691 }
692
693 pub fn segment_bytes(&self) -> usize {
694 self.region.len()
695 }
696
697 pub fn unlink(&self) -> Result<()> {
699 if let Some(access) = &self.group {
700 return access.unlink_region(&self.region).map_err(Error::Io);
701 }
702 self.region.unlink().map_err(Error::Io)
703 }
704}
705
706#[cfg(feature = "tokio")]
708impl Drop for LinkSegment {
709 fn drop(&mut self) {
710 if self.producer_bell.get_mut().is_ok_and(|bell| bell.is_some()) {
711 self.inbox.unbind_producer();
712 }
713 }
714}
715
716pub struct LinkSegmentHandle(Arc<LinkSegment>);
717
718impl LinkSegmentHandle {
719 pub fn new(segment: Arc<LinkSegment>) -> Self {
720 Self(segment)
721 }
722
723 pub fn segment(&self) -> &Arc<LinkSegment> {
724 &self.0
725 }
726}
727
728#[cfg(target_os = "macos")]
729const SHM_NAME_MAX: usize = 31;
730#[cfg(not(target_os = "macos"))]
731const SHM_NAME_MAX: usize = 255;
732
733pub fn check_name(
735 name: &str,
736 spec: LinkSpec,
737) -> Result<()> {
738 validate_name(name)?;
739 let invalid = |reason: String| {
740 Err(Error::InvalidName { name: name.to_owned(), reason })
741 };
742 let inbox_segment = ring_segment_name(name, spec.inbox_kind);
743 let longest = inbox_segment
744 .len()
745 .max(ring_segment_name(name, spec.streams.kind).len());
746 if longest > SHM_NAME_MAX {
747 let room = name.len().saturating_sub(longest - SHM_NAME_MAX);
748 return invalid(format!(
749 "its segment name is {longest} bytes and this host takes {SHM_NAME_MAX}; at most {room} characters fit"
750 ));
751 }
752 crate::bell::Bell::validate_address(
753 &inbox_segment,
754 usize::from(spec.fleet_capacity.saturating_sub(1)),
755 )
756 .map_err(|error| Error::InvalidName {
757 name: name.to_owned(),
758 reason: format!("its reactor socket address is invalid: {error}"),
759 })?;
760 Ok(())
761}
762
763fn validate_name(name: &str) -> Result<()> {
764 let invalid = |reason: String| {
765 Err(Error::InvalidName { name: name.to_owned(), reason })
766 };
767 if name.is_empty() {
768 return invalid("it is empty".into());
769 }
770 if let Some(bad) = name.chars().find(|character| {
771 !(character.is_ascii_alphanumeric()
772 || matches!(character, '-' | '_' | '.'))
773 }) {
774 return invalid(format!(
775 "'{bad}' is not a letter, a digit, '-', '_' or '.'"
776 ));
777 }
778 Ok(())
779}