Merge pull request #1697 from TheBlueMatt/2022-08-event-docs

Clarify and consolidate event handling requirements

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 3b83726958b3a655b681f9a821d114b5a97e7c8a..81bcb3b8c0a1b409e9bef3dfaeb6bdd96644effc 100644 (file)
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -5671,10 +5671,6 @@ where
        ///
        /// An [`EventHandler`] may safely call back to the provider in order to handle an event.
        /// However, it must not call [`Writeable::write`] as doing so would result in a deadlock.
-       ///
-       /// Pending events are persisted as part of [`ChannelManager`]. While these events are cleared
-       /// when processed, an [`EventHandler`] must be able to handle previously seen events when
-       /// restarting from an old state.
        fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler {
                PersistenceNotifierGuard::optionally_notify(&self.total_consistency_lock, &self.persistence_notifier, || {
                        let mut result = NotifyOption::SkipPersist;

diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs
index e86eae3c813a8af7a3684480171df913ea0883bd..4277e7496abeb8ad8b8de812fc52740e75184095 100644 (file)
--- a/lightning/src/util/events.rs
+++ b/lightning/src/util/events.rs
@@ -1207,11 +1207,17 @@ pub trait OnionMessageProvider {
 ///
 /// # 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.
+/// event since the last invocation.
+///
+/// In order to ensure no [`Event`]s are lost, implementors of this trait will persist [`Event`]s
+/// and replay any unhandled events on startup. An [`Event`] is considered handled when
+/// [`process_pending_events`] returns, thus handlers MUST fully handle [`Event`]s and persist any
+/// relevant changes to disk *before* returning.
+///
+/// Further, because an application may crash between an [`Event`] being handled and the
+/// implementor of this trait being re-serialized, [`Event`] handling must be idempotent - in
+/// effect, [`Event`]s may be replayed.
 ///
 /// 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
@@ -1228,9 +1234,7 @@ pub trait OnionMessageProvider {
 pub trait EventsProvider {
        /// 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).
+       /// See the trait-level documentation for requirements.
        fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler;
 }