dimas_core/traits/
context.rs

1// Copyright © 2024 Stephan Kunz
2#![allow(unused_imports)]
3//! Context traits
4//!
5
6#[doc(hidden)]
7extern crate alloc;
8
9#[cfg(feature = "std")]
10extern crate std;
11
12// region:		--- modules
13use crate::{
14	enums::{OperationState, TaskSignal},
15	error::Result,
16	message_types::{Message, QueryableMsg},
17	utils::selector_from,
18};
19use alloc::{string::String, sync::Arc};
20use core::fmt::Debug;
21#[cfg(feature = "std")]
22use tokio::sync::mpsc::Sender;
23use zenoh::Session;
24// endregion:	--- modules
25
26// region:		--- Context
27/// Typedef for simplified usage
28pub type Context<P> = Arc<dyn ContextAbstraction<Props = P>>;
29
30/// Commonalities for the context
31#[allow(clippy::module_name_repetitions)]
32pub trait ContextAbstraction: Debug + Send + Sync {
33	/// The properties structure
34	type Props;
35
36	/// Get the name
37	#[must_use]
38	fn name(&self) -> Option<&String>;
39
40	/// Get the fully qualified name
41	#[must_use]
42	fn fq_name(&self) -> Option<String>;
43
44	/// Get the [`Context`]s state
45	/// # Panics
46	#[must_use]
47	fn state(&self) -> OperationState;
48
49	/// Set the [`OperationState`].
50	///
51	/// Setting new state is done step by step
52	/// # Errors
53	fn set_state(&self, state: OperationState) -> Result<()>;
54
55	/// Get the uuid
56	#[must_use]
57	fn uuid(&self) -> String;
58
59	/// Get prefix
60	#[must_use]
61	fn prefix(&self) -> Option<&String>;
62
63	/// Get session mode
64	#[must_use]
65	fn mode(&self) -> &String;
66
67	/// Get default session reference
68	#[must_use]
69	fn default_session(&self) -> Arc<Session>;
70
71	/// Get session reference
72	#[must_use]
73	fn session(&self, session_id: &str) -> Option<Arc<Session>>;
74
75	/// Get sender reference
76	#[must_use]
77	fn sender(&self) -> &Sender<TaskSignal>;
78
79	/// Gives read access to the properties
80	///
81	/// # Errors
82	fn read(&self) -> Result<std::sync::RwLockReadGuard<'_, Self::Props>>;
83
84	/// Gives write access to the properties
85	///
86	/// # Errors
87	fn write(&self) -> Result<std::sync::RwLockWriteGuard<'_, Self::Props>>;
88
89	/// Method to do a publishing for a `topic`
90	/// The `topic` will be enhanced with the prefix.
91	/// If there is a publisher stored, it will be used
92	/// otherwise an ad-hoc publishing will be done
93	///
94	/// # Errors
95	fn put(&self, topic: &str, message: Message) -> Result<()> {
96		let selector = selector_from(topic, self.prefix());
97		self.put_with(&selector, message)
98	}
99
100	/// Method to do a publishing for a `selector`
101	/// If there is a publisher stored, it will be used
102	/// otherwise an ad-hoc publishing will be done
103	///
104	/// # Errors
105	fn put_with(&self, selector: &str, message: Message) -> Result<()>;
106
107	/// Method to do a deletion for a `topic`
108	/// The `topic` will be enhanced with the prefix.
109	/// If there is a publisher stored, it will be used
110	/// otherwise an ad-hoc deletion will be done
111	///
112	/// # Errors
113	fn delete(&self, topic: &str) -> Result<()> {
114		let selector = selector_from(topic, self.prefix());
115		self.delete_with(&selector)
116	}
117
118	/// Method to do a deletion for a `selector`
119	/// If there is a publisher stored, it will be used
120	/// otherwise an ad-hoc deletion will be done
121	///
122	/// # Errors
123	fn delete_with(&self, selector: &str) -> Result<()>;
124
125	/// Send a query for a `topic` with an optional [`Message`].
126	/// The `topic` will be enhanced with the prefix.
127	/// If there is a query stored, it will be used
128	/// otherwise an ad-hoc query will be done
129	/// If a callback is given for a stored query,
130	/// it will be called instead of the stored callback
131	///
132	/// # Errors
133	fn get(
134		&self,
135		topic: &str,
136		message: Option<Message>,
137		callback: Option<&mut dyn FnMut(QueryableMsg) -> Result<()>>,
138	) -> Result<()> {
139		let selector = selector_from(topic, self.prefix());
140		self.get_with(&selector, message, callback)
141	}
142
143	/// Send a query for a `selector` with an optional [`Message`].
144	/// The `topic` will be enhanced with the prefix.
145	/// If there is a query stored, it will be used
146	/// otherwise an ad-hoc query will be done
147	/// If a callback is given for a stored query,
148	/// it will be called instead of the stored callback
149	///
150	/// # Errors
151	fn get_with(
152		&self,
153		selector: &str,
154		message: Option<Message>,
155		callback: Option<&mut dyn FnMut(QueryableMsg) -> Result<()>>,
156	) -> Result<()>;
157
158	/// Send an observation request for a `topic` with a [`Message`].
159	/// The `topic` will be enhanced with the prefix.
160	///
161	/// # Errors
162	fn observe(&self, topic: &str, message: Option<Message>) -> Result<()> {
163		let selector = selector_from(topic, self.prefix());
164		self.observe_with(&selector, message)
165	}
166
167	/// Send an observation request for a `selector` with a [`Message`].
168	///
169	/// # Errors
170	fn observe_with(&self, selector: &str, message: Option<Message>) -> Result<()>;
171
172	/// Cancel an observation request for a `topic`.
173	/// The `topic` will be enhanced with the prefix.
174	///
175	/// # Errors
176	fn cancel_observe(&self, topic: &str) -> Result<()> {
177		let selector = selector_from(topic, self.prefix());
178		self.cancel_observe_with(&selector)
179	}
180
181	/// Cancel an observation request for a `selector`.
182	///
183	/// # Errors
184	fn cancel_observe_with(&self, selector: &str) -> Result<()>;
185}
186// endregion:	--- Context
dimas_core/traits/context.rs

dimas_core/traits/
context.rs
