f - Document expectations around handling duplicate events

Author: jkczyz

lightning/src/util/events.rs

@@ -388,13 +388,20 @@ pub trait MessageSendEventsProvider {
 ///
 /// [`process_pending_events`]: Self::process_pending_events
 pub trait EventsProvider {
-	/// Processes any generated events with the given event handler.
+	/// 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::process_pending_events`] for details that must be considered when
+	/// implementing this method.
 	fn handle_event(&self, event: Event);
 }