1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265
// Copyright 2015 MaidSafe.net limited. // // This SAFE Network Software is licensed to you under (1) the MaidSafe.net Commercial License, // version 1.0 or later, or (2) The General Public License (GPL), version 3, depending on which // licence you accepted on initial access to the Software (the "Licences"). // // By contributing code to the SAFE Network Software, or to this project generally, you agree to be // bound by the terms of the MaidSafe Contributor Agreement, version 1.0. This, along with the // Licenses can be found in the root directory of this project at LICENSE, COPYING and CONTRIBUTOR. // // Unless required by applicable law or agreed to in writing, the SAFE Network Software distributed // under the GPL Licence is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY // KIND, either express or implied. // // Please review the Licences for the specific language governing permissions and limitations // relating to use of the SAFE Network Software. use std::fmt; use std::sync::mpsc; /// Errors that can be returned by `EventSender` #[derive(Debug)] pub enum EventSenderError<Category, EventSubset> { /// Error sending the event subset EventSubset(mpsc::SendError<EventSubset>), /// Error sending the event category Category(mpsc::SendError<Category>), } /// This structure is coded to achieve event-subsetting. Receivers in Rust are blocking. One cannot /// listen to multiple receivers at the same time except by using `try_recv` which again is bad for /// the same reasons spin-lock based on some sleep is bad (wasting cycles, 50% efficient on an /// average etc.). /// /// Consider a module that listens to signals from various other modules. Different /// modules want to talk to this one. So one solution is make a common event set and all senders /// (registered in all the interested modules) send events from the same set. This is bad for /// maintenance. Wrong modules might use events not expected to originate from them since it is just /// one huge event-set. Thus there is a need of event-subsetting and distribute this module-wise so /// we prevent modules from using wrong events, completely by design and code-mechanics. /// /// We also don't want to spawn threads listening to different receivers (which could force shared /// ownership and is anyway silly otherwise too). This is what `EventSender` helps to salvage. A /// simple mechanism that does what a `skip-list` in linked list does. It brings forth a concept of /// an Umbrella event-category and an event subset. The creator of `EventSender` hard-codes the /// category for different observers. Each category only links to a particular event-subset and /// type information of this is put into `EventSender` too during its construction. Thus when /// distributed, the modules cannot cheat (do the wrong thing) by trying to fire an event they are /// not permitted to. Also a single thread listens to many receivers. All problems solved. /// /// #Examples /// /// ``` /// # #![allow(dead_code)] /// # #[macro_use] /// # extern crate maidsafe_utilities; /// # fn main() { /// #[derive(Debug, Clone)] /// enum EventCategory { /// Network, /// UserInterface, /// } /// /// #[derive(Debug)] /// enum NetworkEvent { /// Connected, /// Disconnected, /// } /// /// #[derive(Debug)] /// enum UiEvent { /// CreateDirectory, /// Terminate, /// } /// /// let (ui_event_tx, ui_event_rx) = std::sync::mpsc::channel(); /// let (category_tx, category_rx) = std::sync::mpsc::channel(); /// let (network_event_tx, network_event_rx) = std::sync::mpsc::channel(); /// /// let ui_event_sender = maidsafe_utilities::event_sender /// ::EventSender::<EventCategory, UiEvent> /// ::new(ui_event_tx, /// EventCategory::UserInterface, /// category_tx.clone()); /// /// let nw_event_sender = maidsafe_utilities::event_sender /// ::EventSender::<EventCategory, NetworkEvent> /// ::new(network_event_tx, /// EventCategory::Network, /// category_tx); /// /// let _joiner = maidsafe_utilities::thread::named("EventListenerThread", move || { /// for it in category_rx.iter() { /// match it { /// EventCategory::Network => { /// if let Ok(network_event) = network_event_rx.try_recv() { /// match network_event { /// NetworkEvent::Connected => { /* Do Something */ }, /// NetworkEvent::Disconnected => { /* Do Something */ }, /// } /// } /// }, /// EventCategory::UserInterface => { /// if let Ok(ui_event) = ui_event_rx.try_recv() { /// match ui_event { /// UiEvent::Terminate => break, /// UiEvent::CreateDirectory => { /* Do Something */ }, /// } /// } /// } /// } /// } /// }); /// /// assert!(nw_event_sender.send(NetworkEvent::Connected).is_ok()); /// assert!(ui_event_sender.send(UiEvent::CreateDirectory).is_ok()); /// assert!(ui_event_sender.send(UiEvent::Terminate).is_ok()); /// # } #[derive(Debug)] pub struct EventSender<Category, EventSubset> { event_tx: mpsc::Sender<EventSubset>, event_category: Category, event_category_tx: mpsc::Sender<Category>, } impl<Category: fmt::Debug + Clone, EventSubset: fmt::Debug> EventSender<Category, EventSubset> { /// Create a new instance of `EventSender`. Category type, category value and EventSubset type /// are baked into `EventSender` to disallow user code from misusing it. pub fn new(event_tx: mpsc::Sender<EventSubset>, event_category: Category, event_category_tx: mpsc::Sender<Category>) -> EventSender<Category, EventSubset> { EventSender { event_tx: event_tx, event_category: event_category, event_category_tx: event_category_tx, } } /// Fire an allowed event/signal to the observer. pub fn send(&self, event: EventSubset) -> Result<(), EventSenderError<Category, EventSubset>> { if let Err(error) = self.event_tx.send(event) { return Err(EventSenderError::EventSubset(error)); } if let Err(error) = self.event_category_tx.send(self.event_category.clone()) { return Err(EventSenderError::Category(error)); } Ok(()) } } // (Spandan) Need to manually implement this because the default derived one seems faulty in that // it requires EventSubset to be clonable even though mpsc::Sender<EventSubset> does // not require EventSubset to be clonable for itself being cloned. impl<Category: fmt::Debug + Clone, EventSubset: fmt::Debug> Clone for EventSender<Category, EventSubset> { fn clone(&self) -> EventSender<Category, EventSubset> { EventSender { event_tx: self.event_tx.clone(), event_category: self.event_category.clone(), event_category_tx: self.event_category_tx.clone(), } } } /// Category of events meant for a MaidSafe observer listening to both, routing and crust events #[derive(Clone, Debug)] pub enum MaidSafeEventCategory { /// Used by Crust to indicate a Crust Event has been fired Crust, /// Used by Routing to indicate a Routing Event has been fired Routing, } /// Observer that Crust (and users of Routing if required) must allow to be registered pub type MaidSafeObserver<EventSubset> = EventSender<MaidSafeEventCategory, EventSubset>; #[cfg(test)] mod test { use super::*; use std::sync::mpsc; #[test] fn marshall_multiple_events() { type UiEventSender = EventSender<EventCategory, UiEvent>; type NetworkEventSender = EventSender<EventCategory, NetworkEvent>; const TOKEN: u32 = 9876; const DIR_NAME: &'static str = "NewDirectory"; #[derive(Clone, Debug)] enum EventCategory { Network, UserInterface, } #[derive(Debug)] enum NetworkEvent { Connected(u32), Disconnected, } #[derive(Debug)] enum UiEvent { CreateDirectory(String), Terminate, } let (ui_event_tx, ui_event_rx) = mpsc::channel(); let (category_tx, category_rx) = mpsc::channel(); let (network_event_tx, network_event_rx) = mpsc::channel(); let ui_event_sender = UiEventSender::new(ui_event_tx, EventCategory::UserInterface, category_tx.clone()); let nw_event_sender = NetworkEventSender::new(network_event_tx, EventCategory::Network, category_tx); let _joiner = ::thread::named("EventListenerThread", move || { for it in category_rx.iter() { match it { EventCategory::Network => { if let Ok(network_event) = network_event_rx.try_recv() { if let NetworkEvent::Connected(token) = network_event { assert_eq!(token, TOKEN) } else { panic!("Shouldn't have received this event: {:?}", network_event) } } } EventCategory::UserInterface => { if let Ok(ui_event) = ui_event_rx.try_recv() { match ui_event { UiEvent::CreateDirectory(name) => assert_eq!(name, DIR_NAME), UiEvent::Terminate => break, } } } } } }); assert!(nw_event_sender.send(NetworkEvent::Connected(TOKEN)).is_ok()); assert!(ui_event_sender.send(UiEvent::CreateDirectory(DIR_NAME.to_string())).is_ok()); assert!(ui_event_sender.send(UiEvent::Terminate).is_ok()); ::std::thread::sleep(::std::time::Duration::from_millis(500)); assert!(ui_event_sender.send(UiEvent::Terminate).is_err()); assert!(nw_event_sender.send(NetworkEvent::Disconnected).is_err()); let result = ui_event_sender.send(UiEvent::CreateDirectory(DIR_NAME.to_owned())).err(); if let EventSenderError::EventSubset(send_err) = unwrap!(result) { if let UiEvent::CreateDirectory(dir_name) = send_err.0 { assert_eq!(dir_name, DIR_NAME) } else { panic!("Expected a different event !") } } else { panic!("Expected a different error !") } } }