maple_runtime/runtime_core/
handle.rs

1//! Handles for interacting with runtime entities
2
3use crate::runtime_core::MapleRuntime;
4use crate::types::*;
5
6/// Handle to a registered Resonator
7///
8/// This handle provides access to Resonator operations while maintaining
9/// safety guarantees.
10#[derive(Clone)]
11pub struct ResonatorHandle {
12    pub id: ResonatorId,
13    runtime: MapleRuntime,
14}
15
16impl ResonatorHandle {
17    pub(crate) fn new(id: ResonatorId, runtime: MapleRuntime) -> Self {
18        Self { id, runtime }
19    }
20
21    /// Signal presence
22    pub async fn signal_presence(&self, state: PresenceState) -> Result<(), PresenceError> {
23        self.runtime
24            .presence_fabric()
25            .signal_presence(self.id, state)
26            .await
27    }
28
29    /// Enable silent mode
30    pub async fn enable_silent_mode(&self) {
31        self.runtime
32            .presence_fabric()
33            .enable_silent_presence(self.id)
34            .await
35    }
36
37    /// Get current presence state
38    pub fn get_presence(&self) -> Option<PresenceState> {
39        self.runtime.presence_fabric().get_presence(&self.id)
40    }
41
42    /// Establish coupling with another Resonator
43    pub async fn couple_with(
44        &self,
45        _target: ResonatorId,
46        params: CouplingParams,
47    ) -> Result<CouplingHandle, CouplingError> {
48        let (coupling_id, attention_token) = self
49            .runtime
50            .coupling_fabric()
51            .establish_coupling(params)
52            .await?;
53
54        Ok(CouplingHandle::new(
55            coupling_id,
56            attention_token,
57            self.runtime.clone(),
58        ))
59    }
60
61    /// Get attention budget status
62    pub async fn attention_status(&self) -> Option<AttentionBudget> {
63        self.runtime
64            .attention_allocator()
65            .get_budget(&self.id)
66            .await
67    }
68}
69
70/// Handle to a coupling relationship
71#[derive(Clone)]
72pub struct CouplingHandle {
73    pub id: CouplingId,
74    _attention_token: AllocationToken,
75    runtime: MapleRuntime,
76}
77
78impl CouplingHandle {
79    pub(crate) fn new(
80        id: CouplingId,
81        attention_token: AllocationToken,
82        runtime: MapleRuntime,
83    ) -> Self {
84        Self {
85            id,
86            _attention_token: attention_token,
87            runtime,
88        }
89    }
90
91    /// Strengthen the coupling
92    pub async fn strengthen(&self, delta: f64) -> Result<(), CouplingError> {
93        self.runtime
94            .coupling_fabric()
95            .strengthen(self.id, delta)
96            .await
97    }
98
99    /// Weaken the coupling
100    pub async fn weaken(&self, factor: f64) -> Result<(), CouplingError> {
101        self.runtime.coupling_fabric().weaken(self.id, factor).await
102    }
103
104    /// Safely sever the coupling
105    pub async fn decouple(self) -> Result<DecouplingResult, CouplingError> {
106        self.runtime
107            .coupling_fabric()
108            .decouple_safely(self.id)
109            .await
110    }
111
112    /// Get coupling state
113    pub fn get_coupling(&self) -> Option<Coupling> {
114        self.runtime.coupling_fabric().get_coupling(&self.id)
115    }
116}
117
118/// Result of decoupling operation
119#[derive(Debug, Clone)]
120pub enum DecouplingResult {
121    Success,
122    PartialSuccess { reason: String },
123}
124
125/// Handle to a scheduled resonance task
126#[derive(Debug, Clone)]
127pub struct ScheduleHandle {
128    pub task_id: Option<TaskId>,
129    pub status: ScheduleStatus,
130}
131
132impl ScheduleHandle {
133    pub(crate) fn scheduled(task_id: TaskId) -> Self {
134        Self {
135            task_id: Some(task_id),
136            status: ScheduleStatus::Scheduled,
137        }
138    }
139
140    pub(crate) fn rejected(reason: RejectionReason) -> Self {
141        Self {
142            task_id: None,
143            status: ScheduleStatus::Rejected(reason),
144        }
145    }
146
147    pub(crate) fn deferred(reason: DeferralReason) -> Self {
148        Self {
149            task_id: None,
150            status: ScheduleStatus::Deferred(reason),
151        }
152    }
153}
154
155#[derive(Debug, Clone)]
156pub enum ScheduleStatus {
157    Scheduled,
158    Rejected(RejectionReason),
159    Deferred(DeferralReason),
160}
161
162#[derive(Debug, Clone)]
163pub enum RejectionReason {
164    CircuitOpen,
165    AttentionUnavailable,
166    QueueFull,
167}
168
169#[derive(Debug, Clone)]
170pub enum DeferralReason {
171    AttentionUnavailable,
172    BackPressure,
173}
174
175/// Task identifier
176#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
177pub struct TaskId(uuid::Uuid);
178
179impl TaskId {
180    pub fn generate() -> Self {
181        Self(uuid::Uuid::new_v4())
182    }
183}
184
185impl std::fmt::Display for TaskId {
186    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
187        write!(f, "task:{}", self.0)
188    }
189}
maple_runtime/runtime_core/handle.rs

maple_runtime/runtime_core/
handle.rs
