Skip to main content

orbit_link/
segment.rs

1//! Bind the lossless inbox layout to one named shared-memory segment.
2
3#[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
15/// A mapped inbox table and the region that keeps it mapped.
16pub 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    /// Cold-open recovery is reported by the next successful join too.
24    reclaimed: Mutex<Vec<Reclaimed>>,
25    #[cfg(feature = "tokio")]
26    receivers: Mutex<HashSet<usize>>,
27    /// Bound the first time this producer waits for a record, then kept.
28    #[cfg(feature = "tokio")]
29    producer_bell: Mutex<Option<Arc<tokio::net::UnixDatagram>>>,
30}
31
32/// A lane this process holds.
33///
34/// The kernel releases `hold` if the process dies. `reclaimed` identifies
35/// lanes this join took back so their stream sides can be ended by exact
36/// node/incarnation rather than by a timeout.
37///
38/// On orderly shutdown, call [`Inbox::release_lane`] before dropping `hold`.
39/// An abrupt exit needs no cleanup: the kernel releases the hold, and the
40/// next join reclaims the still-advertised lane.
41pub 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    /// The inbox epoch owned by this membership.
51    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    /// Open or create one named link inbox.
66    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    /// Attach an existing owner-only link inbox and adopt the shape its
75    /// owner declared, read from the inbox and stream-table headers. Never
76    /// creates: `Ok(None)` when the inbox or its stream table does not exist
77    /// yet, so a caller observes an absent owner instead of fixing the
78    /// fleet's shape itself.
79    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        // SAFETY: the mapping holds a header, and its creator finished it
94        // before releasing the initialization lock held here.
95        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    /// Open a dedicated group-shared Link, without sharing any fleet rings.
117    /// The configured owner creates resources; other users attach existing ones.
118    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    /// `create: false` attaches existing owner-only resources only.
128    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            // Provision streams before publishing a joinable inbox. Recovery
148            // and body handles must use this exact access scope as well.
149            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            // No registration is needed to retire an abandoned inbox. Do
209            // this before one bounded retry, otherwise retained references
210            // can prevent the mapping needed to reach join-time recovery.
211            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    /// Wait until the owner of `name` has created its Link, then adopt it
225    /// as [`LinkSegment::adopt`] does. For a process that runs the fleet's
226    /// processes without creating their Link: it starts the process that
227    /// creates it, then waits here.
228    ///
229    /// No deadline and no poll. The adopter binds its bell before it looks;
230    /// the creator rings it once the inbox exists and again whenever a
231    /// stream table is opened through the segment, and each ring means only
232    /// "look again". One adopter per Link: a second gets
233    /// [`Error::NoWatcher`]. Owner-only Links only.
234    #[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        // Producer holds use a disjoint suffix of the lane-lock namespace.
270        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    /// Take a lane after reclaiming abandoned readers and queued work.
283    /// Includes recovery performed while opening this mapping under producer
284    /// registration pressure.
285    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                // A withdrawn owner may have died during drain. End its sides
310                // under the hold before its stamp is replaced by the new claim.
311                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    /// Take back `lane` if its kernel hold is free and it is still claimed or
371    /// retains queued work after withdrawal. `None` when there is nothing to
372    /// retire or its reader is still alive, including during graceful drain.
373    ///
374    /// A join does this for every lane. A writer refused by a lane asks it
375    /// for that lane: a process killed outright leaves its lane claimed and
376    /// filling, so until the next join every writer would keep finding it
377    /// full. Reclaiming announces the directory, so watchers see the
378    /// departure as they see an orderly one.
379    pub fn reclaim_if_gone(
380        &self,
381        lane: usize,
382    ) -> Result<Option<Reclaimed>> {
383        self.reclaim_if_gone_with(lane, |_| {})
384    }
385
386    /// Run resource recovery while the reclaimed lane is still kernel-held,
387    /// before another participant can publish a replacement on that index.
388    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                // The hold proves reader quiescence even for a lane already
423                // withdrawn from routing. Retirement frees committed slot
424                // references; it never cancels a still-live writer borrow.
425                self.inbox.retire_lane(lane)?;
426                Ok(gone)
427            }
428            None => Ok(None),
429        }
430    }
431
432    /// Recover only lanes last owned by this exact process incarnation.
433    /// The caller has observed process exit; the kernel hold additionally
434    /// fences this scan against a concurrent claim. Withdrawn lanes retain
435    /// their stamp so a process dying during graceful drain is covered too.
436    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    /// Wait until the kernel has released the lane of this exited process, so
464    /// that [`Self::reclaim_process`] can prove the death. An exit notification
465    /// can arrive first. Blocks, and only a live holder prolongs it: a lane
466    /// another process already took back returns at once.
467    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    /// Recover producer reservations after a native exit notification, or on
484    /// a cold join. No PID liveness probe, timed scan or write-path lock.
485    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    /// Bind this process's claimed lane to the current Tokio reactor.
510    ///
511    /// One receiver owns one lane. Frames remain authoritative in SHM; the
512    /// named datagram is only a coalescing wake that tells the task to inspect
513    /// them. The receiver therefore loses neither a frame committed before it
514    /// binds nor one committed while its future is cancelled.
515    #[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    /// Watch the lane directory without holding a lane.
542    ///
543    /// For a process that serves nothing but needs to know who joined or left
544    /// — a master whose workers hold the lanes. The watcher takes the first
545    /// free slot; a slot whose holder died is free, because the kernel
546    /// released its hold. It is woken by the same claim and release that wake
547    /// every lane, and never appears in the directory itself. `role` says
548    /// what the watching process is, in a lane's words (`edge`, `php`), so a
549    /// reader can tell which side of a link it is on.
550    #[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    /// Wait until a reader frees one of this producer's records, after a
575    /// write returned [`Error::ProducerBusy`]; then write again.
576    ///
577    /// No deadline and no poll: the reader that frees a record rings this
578    /// producer, and only while it waits. Returns at once when a record is
579    /// already free. Several tasks may wait together; a ring wakes them all
580    /// and each writes again. The bell is bound on first use and registers
581    /// with the calling Tokio runtime, so a segment waits from one runtime.
582    #[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        // Drain obsolete rings before arming, so the next readiness is new.
598        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    /// Open body streams in this Link's exact IPC scope, not its caller's UID.
623    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                // The stream table may be what an adopter still waits for.
644                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    /// Remove the inbox name. Existing mappings remain valid.
698    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/// A shareable lifecycle handle for registries and providers.
707#[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
733/// Validate the fleet name before opening either physical resource.
734pub 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}