X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FBackgroundProcessor.java;h=af09b461545edb6d781f2a135b291871c377b308;hb=ff3dacec3be60f870d81f6df11bd9fff92aa6047;hp=9858c5d5ec82cab87e18da9bcac8c9318796525b;hpb=ba1af51214a8ea2de62b84cd23b6145173c71752;p=ldk-java diff --git a/src/main/java/org/ldk/structs/BackgroundProcessor.java b/src/main/java/org/ldk/structs/BackgroundProcessor.java index 9858c5d5..af09b461 100644 --- a/src/main/java/org/ldk/structs/BackgroundProcessor.java +++ b/src/main/java/org/ldk/structs/BackgroundProcessor.java @@ -4,24 +4,36 @@ import org.ldk.impl.bindings; import org.ldk.enums.*; import org.ldk.util.*; import java.util.Arrays; +import java.lang.ref.Reference; import javax.annotation.Nullable; /** - * BackgroundProcessor takes care of tasks that (1) need to happen periodically to keep + * `BackgroundProcessor` takes care of tasks that (1) need to happen periodically to keep * Rust-Lightning running properly, and (2) either can or should be run in the background. Its * responsibilities are: - * Monitoring whether the ChannelManager needs to be re-persisted to disk, and if so, + * Processing [`Event`]s with a user-provided [`EventHandler`]. + * Monitoring whether the [`ChannelManager`] needs to be re-persisted to disk, and if so, * writing it to disk/backups by invoking the callback given to it at startup. - * ChannelManager persistence should be done in the background. - * Calling `ChannelManager::timer_tick_occurred()` and - * `PeerManager::timer_tick_occurred()` every minute (can be done in the - * background). + * [`ChannelManager`] persistence should be done in the background. + * Calling [`ChannelManager::timer_tick_occurred`] and [`PeerManager::timer_tick_occurred`] + * at the appropriate intervals. + * Calling [`NetworkGraph::remove_stale_channels`] (if a [`NetGraphMsgHandler`] is provided to + * [`BackgroundProcessor::start`]). * - * Note that if ChannelManager persistence fails and the persisted manager becomes out-of-date, - * then there is a risk of channels force-closing on startup when the manager realizes it's - * outdated. However, as long as `ChannelMonitor` backups are sound, no funds besides those used - * for unilateral chain closure fees are at risk. + * It will also call [`PeerManager::process_events`] periodically though this shouldn't be relied + * upon as doing so may result in high latency. + * + * # Note + * + * If [`ChannelManager`] persistence fails and the persisted manager becomes out-of-date, then + * there is a risk of channels force-closing on startup when the manager realizes it's outdated. + * However, as long as [`ChannelMonitor`] backups are sound, no funds besides those used for + * unilateral chain closure fees are at risk. + * + * [`ChannelMonitor`]: lightning::chain::channelmonitor::ChannelMonitor + * [`Event`]: lightning::util::events::Event + * BackgroundProcessor will immediately stop on drop. It should be stored until shutdown. */ @SuppressWarnings("unchecked") // We correctly assign various generic arrays public class BackgroundProcessor extends CommonBase { @@ -33,45 +45,112 @@ public class BackgroundProcessor extends CommonBase { } /** - * Start a background thread that takes care of responsibilities enumerated in the top-level - * documentation. + * Start a background thread that takes care of responsibilities enumerated in the [top-level + * documentation]. + * + * The thread runs indefinitely unless the object is dropped, [`stop`] is called, or + * [`Persister::persist_manager`] returns an error. In case of an error, the error is retrieved by calling + * either [`join`] or [`stop`]. * - * If `persist_manager` returns an error, then this thread will return said error (and - * `start()` will need to be called again to restart the `BackgroundProcessor`). Users should - * wait on [`thread_handle`]'s `join()` method to be able to tell if and when an error is - * returned, or implement `persist_manager` such that an error is never returned to the - * `BackgroundProcessor` + * # Data Persistence * - * `persist_manager` is responsible for writing out the [`ChannelManager`] to disk, and/or + * [`Persister::persist_manager`] is responsible for writing out the [`ChannelManager`] to disk, and/or * uploading to one or more backup services. See [`ChannelManager::write`] for writing out a * [`ChannelManager`]. See [`FilesystemPersister::persist_manager`] for Rust-Lightning's * provided implementation. * - * [`thread_handle`]: BackgroundProcessor::thread_handle + * [`Persister::persist_graph`] is responsible for writing out the [`NetworkGraph`] to disk. See + * [`NetworkGraph::write`] for writing out a [`NetworkGraph`]. See [`FilesystemPersister::persist_network_graph`] + * for Rust-Lightning's provided implementation. + * + * Typically, users should either implement [`Persister::persist_manager`] to never return an + * error or call [`join`] and handle any error that may arise. For the latter case, + * `BackgroundProcessor` must be restarted by calling `start` again after handling the error. + * + * # Event Handling + * + * `event_handler` is responsible for handling events that users should be notified of (e.g., + * payment failed). [`BackgroundProcessor`] may decorate the given [`EventHandler`] with common + * functionality implemented by other handlers. + * [`NetGraphMsgHandler`] if given will update the [`NetworkGraph`] based on payment failures. + * + * [top-level documentation]: BackgroundProcessor + * [`join`]: Self::join + * [`stop`]: Self::stop * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager * [`ChannelManager::write`]: lightning::ln::channelmanager::ChannelManager#impl-Writeable * [`FilesystemPersister::persist_manager`]: lightning_persister::FilesystemPersister::persist_manager + * [`FilesystemPersister::persist_network_graph`]: lightning_persister::FilesystemPersister::persist_network_graph + * [`NetworkGraph`]: lightning::routing::network_graph::NetworkGraph + * [`NetworkGraph::write`]: lightning::routing::network_graph::NetworkGraph#impl-Writeable + * + * Note that net_graph_msg_handler (or a relevant inner pointer) may be NULL or all-0s to represent None */ - public static BackgroundProcessor start(ChannelManagerPersister persister, EventHandler event_handler, ChainMonitor chain_monitor, ChannelManager channel_manager, PeerManager peer_manager, Logger logger) { - 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); - if (ret < 1024) { return null; } - BackgroundProcessor ret_hu_conv = new BackgroundProcessor(null, ret); + public static BackgroundProcessor start(Persister persister, EventHandler event_handler, ChainMonitor chain_monitor, ChannelManager channel_manager, @Nullable NetGraphMsgHandler net_graph_msg_handler, PeerManager peer_manager, Logger logger) { + 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, net_graph_msg_handler == null ? 0 : net_graph_msg_handler.ptr & ~1, peer_manager == null ? 0 : peer_manager.ptr & ~1, logger == null ? 0 : logger.ptr); + Reference.reachabilityFence(persister); + Reference.reachabilityFence(event_handler); + Reference.reachabilityFence(chain_monitor); + Reference.reachabilityFence(channel_manager); + Reference.reachabilityFence(net_graph_msg_handler); + Reference.reachabilityFence(peer_manager); + Reference.reachabilityFence(logger); + if (ret >= 0 && ret <= 4096) { return null; } + BackgroundProcessor ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new BackgroundProcessor(null, ret); } ret_hu_conv.ptrs_to.add(ret_hu_conv); ret_hu_conv.ptrs_to.add(persister); ret_hu_conv.ptrs_to.add(event_handler); ret_hu_conv.ptrs_to.add(chain_monitor); ret_hu_conv.ptrs_to.add(channel_manager); + ret_hu_conv.ptrs_to.add(net_graph_msg_handler); ret_hu_conv.ptrs_to.add(peer_manager); ret_hu_conv.ptrs_to.add(logger); return ret_hu_conv; } /** - * Stop `BackgroundProcessor`'s thread. + * Join `BackgroundProcessor`'s thread, returning any error that occurred while persisting + * [`ChannelManager`]. + * + * # Panics + * + * This function panics if the background thread has panicked such as while persisting or + * handling events. + * + * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager + */ + public Result_NoneErrorZ join() { + long ret = bindings.BackgroundProcessor_join(this.ptr); + Reference.reachabilityFence(this); + if (ret >= 0 && ret <= 4096) { return null; } + Result_NoneErrorZ ret_hu_conv = Result_NoneErrorZ.constr_from_ptr(ret); + this.ptrs_to.add(this); + // Due to rust's strict-ownership memory model, in some cases we need to "move" + // an object to pass exclusive ownership to the function being called. + // In most cases, we avoid this being visible in GC'd languages by cloning the object + // at the FFI layer, creating a new object which Rust can claim ownership of + // However, in some cases (eg here), there is no way to clone an object, and thus + // we actually have to pass full ownership to Rust. + // Thus, after this call, this is reset to null and is now a dummy object. + this.ptr = 0;; + return ret_hu_conv; + } + + /** + * Stop `BackgroundProcessor`'s thread, returning any error that occurred while persisting + * [`ChannelManager`]. + * + * # Panics + * + * This function panics if the background thread has panicked such as while persisting or + * handling events. + * + * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager */ public Result_NoneErrorZ stop() { long ret = bindings.BackgroundProcessor_stop(this.ptr); - if (ret < 1024) { return null; } + Reference.reachabilityFence(this); + if (ret >= 0 && ret <= 4096) { return null; } Result_NoneErrorZ ret_hu_conv = Result_NoneErrorZ.constr_from_ptr(ret); this.ptrs_to.add(this); // Due to rust's strict-ownership memory model, in some cases we need to "move" @@ -81,7 +160,7 @@ public class BackgroundProcessor extends CommonBase { // However, in some cases (eg here), there is no way to clone an object, and thus // we actually have to pass full ownership to Rust. // Thus, after this call, this is reset to null and is now a dummy object. - this.ptr = 0; + this.ptr = 0;; return ret_hu_conv; }