Skip to main content

ic_storage/runtime/custody/
mod.rs

1//! Process-local backing claims, retained by every issued runtime handle.
2#[cfg(not(target_arch = "wasm32"))]
3mod native;
4#[cfg(target_arch = "wasm32")]
5mod wasm;
6
7#[cfg(not(target_arch = "wasm32"))]
8use native::with_claims;
9#[cfg(target_arch = "wasm32")]
10use wasm::with_claims;
11
12use super::RuntimeConstructionError;
13use crate::{Memory, VectorMemory};
14use std::{rc::Rc, sync::Arc};
15
16/// Identity of a physical backing allocation, shared by all of its wrappers.
17/// This is host custody metadata, not a virtual memory ID or durable record.
18#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
19pub struct BackingIdentity(usize);
20
21impl BackingIdentity {
22    /// Identify an Rc-owned backing. Its allocation must remain alive through
23    /// every runtime/handle using this identity. Identify the underlying backing,
24    /// not a newly allocated wrapper or an address inside a growable byte buffer.
25    #[must_use]
26    pub fn of_rc<T: ?Sized>(backing: &Rc<T>) -> Self {
27        Self(Rc::as_ptr(backing).cast::<()>() as usize)
28    }
29
30    /// Identify an Arc-owned backing under the same contract as [`Self::of_rc`].
31    #[must_use]
32    pub fn of_arc<T: ?Sized>(backing: &Arc<T>) -> Self {
33        Self(Arc::as_ptr(backing).cast::<()>() as usize)
34    }
35}
36
37/// Host boundary for a backing whose aliases can be identified consistently.
38///
39/// All wrappers and clones over the same physical backing must return the same
40/// stable identity; independent backings must have different identities. Keep
41/// its identity allocation alive for the backing's complete runtime/handle
42/// lifetime. A wrapper delegates to its underlying backing's implementation.
43/// Obtaining the identity must not read, grow or write backing memory or create
44/// a manager/runtime; use a retained heap identity, not persisted contents.
45/// Implementing Memory alone does not establish this custody contract. Raw IO
46/// and unmanaged managers over a claimed backing remain prohibited; this is not
47/// an isolation boundary against arbitrary linked code or a dishonest backing.
48///
49pub trait MemoryBacking: Memory {
50    /// Return the physical backing identity under the trait's host contract.
51    fn backing_identity(&self) -> BackingIdentity;
52}
53
54impl MemoryBacking for VectorMemory {
55    fn backing_identity(&self) -> BackingIdentity {
56        BackingIdentity::of_rc(self)
57    }
58}
59
60impl<M: MemoryBacking> MemoryBacking for Rc<M> {
61    fn backing_identity(&self) -> BackingIdentity {
62        self.as_ref().backing_identity()
63    }
64}
65
66pub(super) struct BackingClaim(BackingIdentity);
67
68impl BackingClaim {
69    pub fn acquire(memory: &impl MemoryBacking) -> Result<Self, RuntimeConstructionError> {
70        let identity = memory.backing_identity();
71        if with_claims(|claims| claims.insert(identity)) {
72            Ok(Self(identity))
73        } else {
74            Err(RuntimeConstructionError::BackingAlreadyClaimed)
75        }
76    }
77}
78
79impl Drop for BackingClaim {
80    fn drop(&mut self) {
81        with_claims(|claims| claims.remove(&self.0));
82    }
83}