maple_runtime/runtime_core/
handle.rs

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

maple_runtime/runtime_core/
handle.rs
