_ Git - ldk-java/blob - src/main/java/org/ldk/structs/BackgroundProcessor.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import javax.annotation.Nullable;
   8
   9
  10 /**
  11  * BackgroundProcessor takes care of tasks that (1) need to happen periodically to keep
  12  * Rust-Lightning running properly, and (2) either can or should be run in the background. Its
  13  * responsibilities are:
  14  * Monitoring whether the ChannelManager needs to be re-persisted to disk, and if so,
  15  * writing it to disk/backups by invoking the callback given to it at startup.
  16  * ChannelManager persistence should be done in the background.
  17  * Calling `ChannelManager::timer_tick_occurred()` and
  18  * `PeerManager::timer_tick_occurred()` every minute (can be done in the
  19  * background).
  20  *
  21  * Note that if ChannelManager persistence fails and the persisted manager becomes out-of-date,
  22  * then there is a risk of channels force-closing on startup when the manager realizes it's
  23  * outdated. However, as long as `ChannelMonitor` backups are sound, no funds besides those used
  24  * for unilateral chain closure fees are at risk.
  25  * BackgroundProcessor will immediately stop on drop. It should be stored until shutdown.
  26  */
  27 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  28 public class BackgroundProcessor extends CommonBase {
  29         BackgroundProcessor(Object _dummy, long ptr) { super(ptr); }
  30         @Override @SuppressWarnings("deprecation")
  31         protected void finalize() throws Throwable {
  32                 super.finalize();
  33                 if (ptr != 0) { bindings.BackgroundProcessor_free(ptr); }
  34         }
  35
  36         /**
  37          * Start a background thread that takes care of responsibilities enumerated in the [top-level
  38          * documentation].
  39          *
  40          * The thread runs indefinitely unless the object is dropped, [`stop`] is called, or
  41          * `persist_manager` returns an error. In case of an error, the error is retrieved by calling
  42          * either [`join`] or [`stop`].
  43          *
  44          * Typically, users should either implement [`ChannelManagerPersister`] to never return an
  45          * error or call [`join`] and handle any error that may arise. For the latter case, the
  46          * `BackgroundProcessor` must be restarted by calling `start` again after handling the error.
  47          *
  48          * `persist_manager` is responsible for writing out the [`ChannelManager`] to disk, and/or
  49          * uploading to one or more backup services. See [`ChannelManager::write`] for writing out a
  50          * [`ChannelManager`]. See [`FilesystemPersister::persist_manager`] for Rust-Lightning's
  51          * provided implementation.
  52          *
  53          * [top-level documentation]: Self
  54          * [`join`]: Self::join
  55          * [`stop`]: Self::stop
  56          * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
  57          * [`ChannelManager::write`]: lightning::ln::channelmanager::ChannelManager#impl-Writeable
  58          * [`FilesystemPersister::persist_manager`]: lightning_persister::FilesystemPersister::persist_manager
  59          */
  60         public static BackgroundProcessor start(ChannelManagerPersister persister, EventHandler event_handler, ChainMonitor chain_monitor, ChannelManager channel_manager, PeerManager peer_manager, Logger logger) {
  61                 long ret = bindings.BackgroundProcessor_start(persister == null ? 0 : persister.ptr, event_handler == null ? 0 : event_handler.ptr, chain_monitor == null ? 0 : chain_monitor.ptr & ~1, channel_manager == null ? 0 : channel_manager.ptr & ~1, peer_manager == null ? 0 : peer_manager.ptr & ~1, logger == null ? 0 : logger.ptr);
  62                 if (ret < 1024) { return null; }
  63                 BackgroundProcessor ret_hu_conv = new BackgroundProcessor(null, ret);
  64                 ret_hu_conv.ptrs_to.add(ret_hu_conv);
  65                 ret_hu_conv.ptrs_to.add(persister);
  66                 ret_hu_conv.ptrs_to.add(event_handler);
  67                 ret_hu_conv.ptrs_to.add(chain_monitor);
  68                 ret_hu_conv.ptrs_to.add(channel_manager);
  69                 ret_hu_conv.ptrs_to.add(peer_manager);
  70                 ret_hu_conv.ptrs_to.add(logger);
  71                 return ret_hu_conv;
  72         }
  73
  74         /**
  75          * Join `BackgroundProcessor`'s thread, returning any error that occurred while persisting
  76          * [`ChannelManager`].
  77          *
  78          * # Panics
  79          *
  80          * This function panics if the background thread has panicked such as while persisting or
  81          * handling events.
  82          *
  83          * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
  84          */
  85         public Result_NoneErrorZ join() {
  86                 long ret = bindings.BackgroundProcessor_join(this.ptr);
  87                 if (ret < 1024) { return null; }
  88                 Result_NoneErrorZ ret_hu_conv = Result_NoneErrorZ.constr_from_ptr(ret);
  89                 this.ptrs_to.add(this);
  90                 // Due to rust's strict-ownership memory model, in some cases we need to "move"
  91                 // an object to pass exclusive ownership to the function being called.
  92                 // In most cases, we avoid this being visible in GC'd languages by cloning the object
  93                 // at the FFI layer, creating a new object which Rust can claim ownership of
  94                 // However, in some cases (eg here), there is no way to clone an object, and thus
  95                 // we actually have to pass full ownership to Rust.
  96                 // Thus, after this call, this is reset to null and is now a dummy object.
  97                 this.ptr = 0;
  98                 return ret_hu_conv;
  99         }
 100
 101         /**
 102          * Stop `BackgroundProcessor`'s thread, returning any error that occurred while persisting
 103          * [`ChannelManager`].
 104          *
 105          * # Panics
 106          *
 107          * This function panics if the background thread has panicked such as while persisting or
 108          * handling events.
 109          *
 110          * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
 111          */
 112         public Result_NoneErrorZ stop() {
 113                 long ret = bindings.BackgroundProcessor_stop(this.ptr);
 114                 if (ret < 1024) { return null; }
 115                 Result_NoneErrorZ ret_hu_conv = Result_NoneErrorZ.constr_from_ptr(ret);
 116                 this.ptrs_to.add(this);
 117                 // Due to rust's strict-ownership memory model, in some cases we need to "move"
 118                 // an object to pass exclusive ownership to the function being called.
 119                 // In most cases, we avoid this being visible in GC'd languages by cloning the object
 120                 // at the FFI layer, creating a new object which Rust can claim ownership of
 121                 // However, in some cases (eg here), there is no way to clone an object, and thus
 122                 // we actually have to pass full ownership to Rust.
 123                 // Thus, after this call, this is reset to null and is now a dummy object.
 124                 this.ptr = 0;
 125                 return ret_hu_conv;
 126         }
 127
 128 }