X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FEventsProvider.java;h=f4f22f3933eeacb55f7d063b04a14d2def807a35;hb=5e9de82b3a7712a41189756d9d16d946142b2ac5;hp=0422859b2dcd037d9d941aee271c410c5f41dd1b;hpb=1854b5cebef22ace9e9e4dd191f609818df9ce08;p=ldk-java

diff --git a/src/main/java/org/ldk/structs/EventsProvider.java b/src/main/java/org/ldk/structs/EventsProvider.java
index 0422859b..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);
 	}
@@ -63,8 +67,9 @@ public class EventsProvider extends CommonBase {
 		impl_holder.held = new EventsProvider(new bindings.LDKEventsProvider() {
 			@Override public void process_pending_events(long handler) {
 				EventHandler ret_hu_conv = new EventHandler(null, handler);
-				ret_hu_conv.ptrs_to.add(this);
+				if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 				arg.process_pending_events(ret_hu_conv);
+				Reference.reachabilityFence(arg);
 			}
 		});
 		return impl_holder.held;
@@ -72,15 +77,13 @@ 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);
 		Reference.reachabilityFence(this);
 		Reference.reachabilityFence(handler);
-		this.ptrs_to.add(handler);
+		if (this != null) { this.ptrs_to.add(handler); };
 	}
 
 }