X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FPersist.java;h=db7a6114b84d10f2a8253601422c1a28d75671a0;hb=07d5d868dfe064aadb28a7f7ca6002c16be9723d;hp=b6c56ab9ff718559b6a73a05a0ee1c60a772af33;hpb=0de4267b2f4dd9a0b2b2dfab7efc788887894a33;p=ldk-java

diff --git a/src/main/java/org/ldk/structs/Persist.java b/src/main/java/org/ldk/structs/Persist.java
index b6c56ab9..db7a6114 100644
--- a/src/main/java/org/ldk/structs/Persist.java
+++ b/src/main/java/org/ldk/structs/Persist.java
@@ -11,23 +11,58 @@ import javax.annotation.Nullable;
  * `Persist` defines behavior for persisting channel monitors: this could mean
  * writing once to disk, and/or uploading to one or more backup services.
  * 
- * Each method can return three possible values:
- * If persistence (including any relevant `fsync()` calls) happens immediately, the
- * implementation should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal
- * channel operation should continue.
- * If persistence happens asynchronously, implementations should first ensure the
- * [`ChannelMonitor`] or [`ChannelMonitorUpdate`] are written durably to disk, and then return
- * [`ChannelMonitorUpdateStatus::InProgress`] while the update continues in the background.
- * Once the update completes, [`ChainMonitor::channel_monitor_updated`] should be called with
- * the corresponding [`MonitorUpdateId`].
+ * Persistence can happen in one of two ways - synchronously completing before the trait method
+ * calls return or asynchronously in the background.
+ * 
+ * # For those implementing synchronous persistence
+ * 
+ * If persistence completes fully (including any relevant `fsync()` calls), the implementation
+ * should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal channel operation
+ * should continue.
+ * 
+ * If persistence fails for some reason, implementations should consider returning
+ * [`ChannelMonitorUpdateStatus::InProgress`] and retry all pending persistence operations in
+ * the background with [`ChainMonitor::list_pending_monitor_updates`] and
+ * [`ChainMonitor::get_monitor`].
+ * 
+ * Once a full [`ChannelMonitor`] has been persisted, all pending updates for that channel can
+ * be marked as complete via [`ChainMonitor::channel_monitor_updated`].
+ * 
+ * If at some point no further progress can be made towards persisting the pending updates, the
+ * node should simply shut down.
+ * 
+ * If the persistence has failed and cannot be retried further (e.g. because of an outage),
+ * [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
+ * an immediate panic and future operations in LDK generally failing.
+ * 
+ * # For those implementing asynchronous persistence
+ * 
+ * All calls should generally spawn a background task and immediately return
+ * [`ChannelMonitorUpdateStatus::InProgress`]. Once the update completes,
+ * [`ChainMonitor::channel_monitor_updated`] should be called with the corresponding
+ * [`MonitorUpdateId`].
  * 
  * Note that unlike the direct [`chain::Watch`] interface,
  * [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
  * 
- * If persistence fails for some reason, implementations should return
- * [`ChannelMonitorUpdateStatus::PermanentFailure`], in which case the channel will likely be
- * closed without broadcasting the latest state. See
- * [`ChannelMonitorUpdateStatus::PermanentFailure`] for more details.
+ * If at some point no further progress can be made towards persisting a pending update, the node
+ * should simply shut down. Until then, the background task should either loop indefinitely, or
+ * persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+ * and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+ * monitor updates may be marked completed).
+ * 
+ * # Using remote watchtowers
+ * 
+ * Watchtowers may be updated as a part of an implementation of this trait, utilizing the async
+ * update process described above while the watchtower is being updated. The following methods are
+ * provided for bulding transactions for a watchtower:
+ * [`ChannelMonitor::initial_counterparty_commitment_tx`],
+ * [`ChannelMonitor::counterparty_commitment_txs_from_update`],
+ * [`ChannelMonitor::sign_to_local_justice_tx`], [`TrustedCommitmentTransaction::revokeable_output_index`],
+ * [`TrustedCommitmentTransaction::build_to_local_justice_tx`].
+ * 
+ * [`TrustedCommitmentTransaction::revokeable_output_index`]: crate::ln::chan_utils::TrustedCommitmentTransaction::revokeable_output_index
+ * [`TrustedCommitmentTransaction::build_to_local_justice_tx`]: crate::ln::chan_utils::TrustedCommitmentTransaction::build_to_local_justice_tx
  */
 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
 public class Persist extends CommonBase {
@@ -42,7 +77,19 @@ public class Persist extends CommonBase {
 	protected void finalize() throws Throwable {
 		if (ptr != 0) { bindings.Persist_free(ptr); } super.finalize();
 	}
-
+	/**
+	 * Destroys the object, freeing associated resources. After this call, any access
+	 * to this object may result in a SEGFAULT or worse.
+	 *
+	 * You should generally NEVER call this method. You should let the garbage collector
+	 * do this for you when it finalizes objects. However, it may be useful for types
+	 * which represent locks and should be closed immediately to avoid holding locks
+	 * until the GC runs.
+	 */
+	public void destroy() {
+		if (ptr != 0) { bindings.Persist_free(ptr); }
+		ptr = 0;
+	}
 	public static interface PersistInterface {
 		/**
 		 * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is
@@ -70,8 +117,8 @@ public class Persist extends CommonBase {
 		 * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
 		 * details.
 		 * 
-		 * During blockchain synchronization operations, this may be called with no
-		 * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
+		 * During blockchain synchronization operations, and in some rare cases, this may be called with
+		 * no [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
 		 * Note that after the full [`ChannelMonitor`] is persisted any previous
 		 * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
 		 * applied to the persisted [`ChannelMonitor`] as they were already applied.
@@ -119,6 +166,7 @@ public class Persist extends CommonBase {
 				org.ldk.structs.OutPoint channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new org.ldk.structs.OutPoint(null, channel_id); }
 				if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
 				org.ldk.structs.ChannelMonitorUpdate update_hu_conv = null; if (update < 0 || update > 4096) { update_hu_conv = new org.ldk.structs.ChannelMonitorUpdate(null, update); }
+				if (update_hu_conv != null) { update_hu_conv.ptrs_to.add(this); };
 				org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
 				org.ldk.structs.MonitorUpdateId update_id_hu_conv = null; if (update_id < 0 || update_id > 4096) { update_id_hu_conv = new org.ldk.structs.MonitorUpdateId(null, update_id); }
 				if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
@@ -146,7 +194,7 @@ public class Persist extends CommonBase {
 	 * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 	 * [`Writeable::write`]: crate::util::ser::Writeable::write
 	 */
-	public ChannelMonitorUpdateStatus persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id) {
+	public ChannelMonitorUpdateStatus persist_new_channel(org.ldk.structs.OutPoint channel_id, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
 		ChannelMonitorUpdateStatus ret = bindings.Persist_persist_new_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr, data == null ? 0 : data.ptr, update_id == null ? 0 : update_id.ptr);
 		Reference.reachabilityFence(this);
 		Reference.reachabilityFence(channel_id);
@@ -166,8 +214,8 @@ public class Persist extends CommonBase {
 	 * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more
 	 * details.
 	 * 
-	 * During blockchain synchronization operations, this may be called with no
-	 * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
+	 * During blockchain synchronization operations, and in some rare cases, this may be called with
+	 * no [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted.
 	 * Note that after the full [`ChannelMonitor`] is persisted any previous
 	 * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be
 	 * applied to the persisted [`ChannelMonitor`] as they were already applied.
@@ -195,7 +243,7 @@ public class Persist extends CommonBase {
 	 * 
 	 * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None
 	 */
-	public ChannelMonitorUpdateStatus update_persisted_channel(OutPoint channel_id, @Nullable ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id) {
+	public ChannelMonitorUpdateStatus update_persisted_channel(org.ldk.structs.OutPoint channel_id, @Nullable org.ldk.structs.ChannelMonitorUpdate update, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
 		ChannelMonitorUpdateStatus ret = bindings.Persist_update_persisted_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr, update == null ? 0 : update.ptr, data == null ? 0 : data.ptr, update_id == null ? 0 : update_id.ptr);
 		Reference.reachabilityFence(this);
 		Reference.reachabilityFence(channel_id);