Mountain/ApplicationState/State/FeatureState/Terminals/
TerminalState.rs

1//! # TerminalState Module (ApplicationState)
2//!
3//! ## RESPONSIBILITIES
4//! Manages terminal instances state including terminal metadata, content, and
5//! unique identifier tracking.
6//!
7//! ## ARCHITECTURAL ROLE
8//! TerminalState is part of the **FeatureState** module, representing
9//! terminal instances state organized by terminal ID.
10//!
11//! ## KEY COMPONENTS
12//! - TerminalState: Main struct containing active terminals map and counter
13//! - Default: Initialization implementation
14//! - Helper methods: Terminal manipulation utilities
15//!
16//! ## ERROR HANDLING
17//! - Thread-safe access via `Arc<Mutex<...>>`
18//! - Proper lock error handling with `MapLockError` helpers
19//!
20//! ## LOGGING
21//! State changes are logged at appropriate levels (debug, info, warn, error).
22//!
23//! ## PERFORMANCE CONSIDERATIONS
24//! - Lock mutexes briefly and release immediately
25//! - Avoid nested locks to prevent deadlocks
26//! - Use Arc for shared ownership across threads
27//! - Use double mutex for terminals (outer for map, inner for each terminal)
28//!
29//! ## TODO
30//! - [ ] Add terminal validation invariants
31//! - [ ] Implement terminal lifecycle events
32//! - [ ] Add terminal metrics collection
33
34use std::{
35	collections::HashMap,
36	sync::{
37		Arc,
38		Mutex as StandardMutex,
39		atomic::{AtomicU64, Ordering as AtomicOrdering},
40	},
41};
42
43use crate::{ApplicationState::DTO::TerminalStateDTO::TerminalStateDTO, dev_log};
44
45/// Active terminals state containing terminals by ID with next identifier
46/// counter.
47#[derive(Clone)]
48pub struct TerminalState {
49	/// Active terminals organized by ID.
50	pub ActiveTerminals:Arc<StandardMutex<HashMap<u64, Arc<StandardMutex<TerminalStateDTO>>>>>,
51
52	/// Counter for generating unique terminal identifiers.
53	pub NextTerminalIdentifier:Arc<AtomicU64>,
54}
55
56impl Default for TerminalState {
57	fn default() -> Self {
58		dev_log!("terminal", "[TerminalState] Initializing default terminal state...");
59
60		Self {
61			ActiveTerminals:Arc::new(StandardMutex::new(HashMap::new())),
62
63			NextTerminalIdentifier:Arc::new(AtomicU64::new(1)),
64		}
65	}
66}
67
68impl TerminalState {
69	/// Gets the next available unique identifier for a terminal instance.
70	pub fn GetNextTerminalIdentifier(&self) -> u64 { self.NextTerminalIdentifier.fetch_add(1, AtomicOrdering::Relaxed) }
71
72	/// Gets all active terminals.
73	pub fn GetAll(&self) -> HashMap<u64, TerminalStateDTO> {
74		self.ActiveTerminals
75			.lock()
76			.ok()
77			.map(|guard| {
78				guard
79					.iter()
80					.filter_map(|(id, arc)| arc.lock().ok().map(|dto| (*id, dto.clone())))
81					.collect()
82			})
83			.unwrap_or_default()
84	}
85
86	/// Gets a terminal by its ID.
87	pub fn Get(&self, id:u64) -> Option<TerminalStateDTO> {
88		self.ActiveTerminals
89			.lock()
90			.ok()
91			.and_then(|guard| guard.get(&id).and_then(|arc| arc.lock().ok().map(|dto| dto.clone())))
92	}
93
94	/// Gets a terminal's Arc<Mutex<>> by its ID for direct manipulation.
95	pub fn GetArc(&self, id:u64) -> Option<Arc<StandardMutex<TerminalStateDTO>>> {
96		self.ActiveTerminals.lock().ok().and_then(|guard| guard.get(&id).cloned())
97	}
98
99	/// Adds or updates a terminal.
100	pub fn AddOrUpdate(&self, id:u64, terminal:TerminalStateDTO) {
101		if let Ok(mut guard) = self.ActiveTerminals.lock() {
102			guard.insert(id, Arc::new(StandardMutex::new(terminal)));
103
104			dev_log!("terminal", "[TerminalState] Terminal added/updated with ID: {}", id);
105		}
106	}
107
108	/// Removes a terminal by its ID.
109	pub fn Remove(&self, id:u64) {
110		if let Ok(mut guard) = self.ActiveTerminals.lock() {
111			guard.remove(&id);
112
113			dev_log!("terminal", "[TerminalState] Terminal removed with ID: {}", id);
114		}
115	}
116
117	/// Clears all active terminals.
118	pub fn Clear(&self) {
119		if let Ok(mut guard) = self.ActiveTerminals.lock() {
120			guard.clear();
121
122			dev_log!("terminal", "[TerminalState] All terminals cleared");
123		}
124	}
125
126	/// Gets the count of active terminals.
127	pub fn Count(&self) -> usize { self.ActiveTerminals.lock().ok().map(|guard| guard.len()).unwrap_or(0) }
128
129	/// Checks if a terminal exists.
130	pub fn Contains(&self, id:u64) -> bool {
131		self.ActiveTerminals
132			.lock()
133			.ok()
134			.map(|guard| guard.contains_key(&id))
135			.unwrap_or(false)
136	}
137}
Mountain/ApplicationState/State/FeatureState/Terminals/TerminalState.rs

Mountain/ApplicationState/State/FeatureState/Terminals/
TerminalState.rs
