X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fevents.rs;h=013e3c4e611bbdfb130ca85094911499e65a6da5;hb=7c465d69dcd81d540e6b21ceb46531f22e8414f0;hp=b7b8bf3137b8ea44d6d667842c3b2473b7a8790e;hpb=3a0356fe308ba29916d00f3376cd57ce6613f3d0;p=rust-lightning

diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs
index b7b8bf31..013e3c4e 100644
--- a/lightning/src/util/events.rs
+++ b/lightning/src/util/events.rs
@@ -24,6 +24,7 @@ use bitcoin::blockdata::script::Script;
 use bitcoin::secp256k1::key::PublicKey;
 
 use core::time::Duration;
+use std::ops::Deref;
 
 /// An Event which you should probably take some action in response to.
 ///
@@ -376,9 +377,46 @@ pub trait MessageSendEventsProvider {
 	fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>;
 }
 
-/// A trait indicating an object may generate events
+/// A trait indicating an object may generate events.
+///
+/// Events are processed by passing an [`EventHandler`] to [`process_pending_events`].
+///
+/// # Requirements
+///
+/// See [`process_pending_events`] for requirements around event processing.
+///
+/// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending
+/// event since the last invocation. The handler must either act upon the event immediately
+/// or preserve it for later handling.
+///
+/// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to
+/// consult the provider's documentation on the implication of processing events and how a handler
+/// may safely use the provider (e.g., see [`ChannelManager::process_pending_events`] and
+/// [`ChainMonitor::process_pending_events`]).
+///
+/// [`process_pending_events`]: Self::process_pending_events
+/// [`handle_event`]: EventHandler::handle_event
+/// [`ChannelManager::process_pending_events`]: crate::ln::channelmanager::ChannelManager#method.process_pending_events
+/// [`ChainMonitor::process_pending_events`]: crate::chain::chainmonitor::ChainMonitor#method.process_pending_events
 pub trait EventsProvider {
-	/// Gets the list of pending events which were generated by previous actions, clearing the list
-	/// in the process.
-	fn get_and_clear_pending_events(&self) -> Vec<Event>;
+	/// Processes any events generated since the last call using the given event handler.
+	///
+	/// Subsequent calls must only process new events. However, handlers must be capable of handling
+	/// duplicate events across process restarts. This may occur if the provider was recovered from
+	/// an old state (i.e., it hadn't been successfully persisted after processing pending events).
+	fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler;
+}
+
+/// A trait implemented for objects handling events from [`EventsProvider`].
+pub trait EventHandler {
+	/// Handles the given [`Event`].
+	///
+	/// See [`EventsProvider`] for details that must be considered when implementing this method.
+	fn handle_event(&self, event: Event);
+}
+
+impl<F> EventHandler for F where F: Fn(Event) {
+	fn handle_event(&self, event: Event) {
+		self(event)
+	}
 }