Skip to main content

dive_value/
receiver.rs

1//! Sealed receiver construction facts. They are not value identity or a wire format.
2
3use std::sync::atomic::{AtomicU32, Ordering};
4
5use crate::value::Fcn;
6use crate::{Value, ValueOrder};
7
8const LITERAL: u64 = 1 << 63;
9const TLC_ORDER: u64 = 1 << 62;
10const DIAGNOSTIC: u64 = 1 << 61;
11const DOMAIN_MASK: u32 = (1 << 29) - 1;
12static NEXT_DOMAIN: AtomicU32 = AtomicU32::new(1);
13
14/// One evaluator's nonreused receiver-construction namespace.
15///
16/// The owner keeps this capability private. Exhaustion declines provenance;
17/// it never reuses another owner's identity or affects value semantics.
18///
19/// ```
20/// use dive_value::{Ctx, ReceiverDomain, Value, tlc};
21/// if let Some(owner) = ReceiverDomain::new() {
22///     let tuple = owner.tuple(vec![Value::Int(1)], 7, true);
23///     let caught = tlc::equals(&tuple, &Value::FALSE, Ctx::tlc())
24///         .err().and_then(|error| error.receiver_failure());
25///     assert_eq!(caught.and_then(|failure| owner.recover(failure)), Some((7, true)));
26/// }
27/// ```
28#[derive(Debug)]
29pub struct ReceiverDomain(u32);
30
31impl ReceiverDomain {
32    /// Creates an owner capability, or declines if its packed identity is exhausted.
33    #[must_use]
34    pub fn new() -> Option<Self> {
35        NEXT_DOMAIN
36            .try_update(Ordering::Relaxed, Ordering::Relaxed, |n| {
37                (n < DOMAIN_MASK).then_some(n + 1)
38            })
39            .ok()
40            .map(Self)
41    }
42
43    /// Builds an actual tuple constructor with this owner's source-hook facts.
44    /// Reusing a cached/shared value never calls this constructor.
45    #[must_use]
46    pub fn tuple(&self, values: Vec<Value>, node: u32, diagnostic: bool) -> Value {
47        Value::Fcn(Fcn::tuple_metadata(
48            values,
49            self.metadata(ValueOrder::Canonical, node, diagnostic),
50        ))
51    }
52
53    /// Builds an actual record constructor with this owner's source-hook facts.
54    ///
55    /// # Errors
56    /// Duplicate fields, exactly as `Value::record`.
57    pub fn record(
58        &self,
59        fields: Vec<(crate::Atom, Value)>,
60        ctx: crate::Ctx,
61        node: u32,
62        diagnostic: bool,
63    ) -> crate::Result<Value> {
64        if fields.is_empty() {
65            return Ok(self.tuple(Vec::new(), node, diagnostic));
66        }
67        Ok(Value::Fcn(Fcn::record_metadata(
68            crate::value::sort_fields(fields, ctx.order)?,
69            self.metadata(ctx.order, node, diagnostic),
70        )))
71    }
72
73    fn metadata(&self, order: ValueOrder, node: u32, diagnostic: bool) -> FunctionMetadata {
74        let mut metadata = FunctionMetadata::new(order, true);
75        metadata.0 |= (u64::from(self.0) << 32) | u64::from(node);
76        if diagnostic {
77            metadata.0 |= DIAGNOSTIC;
78        }
79        metadata
80    }
81
82    /// Recovers a catch only for this owner: constructor node and source-hook state.
83    #[must_use]
84    pub fn recover(&self, failure: ReceiverFailure) -> Option<(u32, bool)> {
85        let origin = failure.origin;
86        (origin.domain == self.0).then_some((origin.node, origin.diagnostic))
87    }
88}
89
90/// The actual literal receiver method that caught a value-layer error.
91#[derive(Clone, Copy, Debug, PartialEq, Eq)]
92pub enum ReceiverMethod {
93    /// TLC's `TupleValue.equals`.
94    TupleEquals,
95    /// TLC's `RecordValue.equals`.
96    RecordEquals,
97}
98
99#[derive(Clone, Copy, Debug, PartialEq, Eq)]
100struct ReceiverOrigin {
101    domain: u32,
102    node: u32,
103    diagnostic: bool,
104}
105
106/// A value-method catch with sealed receiver construction, recoverable only by
107/// the evaluator that constructed it. Text and an error code cannot create it.
108#[derive(Clone, Copy, Debug, PartialEq, Eq)]
109pub struct ReceiverFailure {
110    method: ReceiverMethod,
111    origin: ReceiverOrigin,
112}
113
114impl ReceiverFailure {
115    /// The method that actually caught this failure.
116    #[must_use]
117    pub fn method(self) -> ReceiverMethod {
118        self.method
119    }
120
121    pub(crate) const fn sourced(self) -> bool {
122        self.origin.diagnostic
123    }
124
125    pub(crate) fn equals(f: &Fcn) -> Option<Self> {
126        let method = if f.is_tuple_literal() {
127            ReceiverMethod::TupleEquals
128        } else if f.is_record_literal() {
129            ReceiverMethod::RecordEquals
130        } else {
131            return None;
132        };
133        Some(Self {
134            method,
135            origin: f.0.metadata.origin()?,
136        })
137    }
138}
139
140/// Replaces the former order/literal bytes and their padding, not an added
141/// allocation or a larger function header. Never participates in identity.
142#[derive(Clone, Copy)]
143pub(crate) struct FunctionMetadata(pub(crate) u64);
144
145impl FunctionMetadata {
146    pub(crate) const fn new(order: ValueOrder, literal: bool) -> Self {
147        Self(
148            (if literal { LITERAL } else { 0 })
149                | if matches!(order, ValueOrder::Tlc) {
150                    TLC_ORDER
151                } else {
152                    0
153                },
154        )
155    }
156
157    pub(crate) const fn literal(self) -> bool {
158        self.0 & LITERAL != 0
159    }
160
161    pub(crate) const fn order(self) -> ValueOrder {
162        if self.0 & TLC_ORDER == 0 {
163            ValueOrder::Canonical
164        } else {
165            ValueOrder::Tlc
166        }
167    }
168
169    fn origin(self) -> Option<ReceiverOrigin> {
170        let domain = u32::try_from((self.0 >> 32) & u64::from(DOMAIN_MASK)).ok()?;
171        (domain != 0).then_some(ReceiverOrigin {
172            domain,
173            node: u32::try_from(self.0 & u64::from(u32::MAX)).ok()?,
174            diagnostic: self.0 & DIAGNOSTIC != 0,
175        })
176    }
177}
178
179#[cfg(test)]
180mod tests {
181    use super::*;
182    #[test]
183    fn receiver_facts_are_owner_bound_and_do_not_relabel_cached_aliases() {
184        let Some(owner) = ReceiverDomain::new() else {
185            return;
186        };
187        let Some(foreign) = ReceiverDomain::new() else {
188            return;
189        };
190        let value = owner.tuple(vec![Value::Int(1)], 17, false);
191        let hash = value.hash64();
192        let alias = value.clone();
193        let error = crate::tlc::equals(&alias, &Value::FALSE, crate::Ctx::tlc());
194        let failure = error.err().and_then(|e| e.receiver_failure());
195        assert_eq!(failure.and_then(|f| owner.recover(f)), Some((17, false)));
196        assert_eq!(failure.and_then(|f| foreign.recover(f)), None);
197        assert_eq!(value.hash64(), hash);
198        assert_eq!(value, Value::tuple(vec![Value::Int(1)]));
199        assert_eq!(
200            crate::ValueError::new(crate::ErrorKind::Incomparable, "apparent source")
201                .receiver_failure(),
202            None
203        );
204        #[cfg(target_pointer_width = "64")]
205        assert_eq!(std::mem::size_of::<crate::value::FcnInner>(), 64);
206        assert_eq!(std::mem::size_of::<Value>(), 16);
207    }
208}