X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FEventsProvider.java;h=f4f22f3933eeacb55f7d063b04a14d2def807a35;hb=76982ad5233afc2759d085bb243f33149369ab9b;hp=a53de7b532647ffccb19165ee3e1845694b86728;hpb=227672ae3d27961f63d45913aad01dbae1f53e99;p=ldk-java

diff --git a/src/main/java/org/ldk/structs/EventsProvider.java b/src/main/java/org/ldk/structs/EventsProvider.java
index a53de7b5..f4f22f39 100644
--- a/src/main/java/org/ldk/structs/EventsProvider.java
+++ b/src/main/java/org/ldk/structs/EventsProvider.java
@@ -14,11 +14,17 @@ import javax.annotation.Nullable;
  * 
  * # 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
@@ -51,9 +57,7 @@ public class EventsProvider extends CommonBase {
 		/**
 		 * 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.
 		 */
 		void process_pending_events(EventHandler handler);
 	}
@@ -73,9 +77,7 @@ public class EventsProvider extends CommonBase {
 	/**
 	 * 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.
 	 */
 	public void process_pending_events(EventHandler handler) {
 		bindings.EventsProvider_process_pending_events(this.ptr, handler == null ? 0 : handler.ptr);