Struct lightning_background_processor::BackgroundProcessor

pub struct BackgroundProcessor { /* private fields */ }

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:

• Processing Events 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 at the appropriate intervals.
• Calling NetworkGraph::remove_stale_channels_and_tracking (if a GossipSync with a NetworkGraph is provided to BackgroundProcessor::start).

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.

Implementations

impl BackgroundProcessor

pub fn start<'a, Signer: 'static + Sign, CA: 'static + Deref + Send + Sync, CF: 'static + Deref + Send + Sync, CW: 'static + Deref + Send + Sync, T: 'static + Deref + Send + Sync, K: 'static + Deref + Send + Sync, F: 'static + Deref + Send + Sync, G: 'static + Deref<Target = NetworkGraph<L>> + Send + Sync, L: 'static + Deref + Send + Sync, P: 'static + Deref + Send + Sync, Descriptor: 'static + SocketDescriptor + Send + Sync, CMH: 'static + Deref + Send + Sync, OMH: 'static + Deref + Send + Sync, RMH: 'static + Deref + Send + Sync, EH: 'static + EventHandler + Send, PS: 'static + Deref + Send, M: 'static + Deref<Target = ChainMonitor<Signer, CF, T, F, L, P>> + Send + Sync, CM: 'static + Deref<Target = ChannelManager<Signer, CW, T, K, F, L>> + Send + Sync, PGS: 'static + Deref<Target = P2PGossipSync<G, CA, L>> + Send + Sync, RGS: 'static + Deref<Target = RapidGossipSync<G, L>> + Send, UMH: 'static + Deref + Send + Sync, PM: 'static + Deref<Target = PeerManager<Descriptor, CMH, RMH, OMH, L, UMH>> + Send + Sync, S: 'static + Deref<Target = SC> + Send + Sync, SC: WriteableScore<'a>>(
    persister: PS,
    event_handler: EH,
    chain_monitor: M,
    channel_manager: CM,
    gossip_sync: GossipSync<PGS, RGS, G, CA, L>,
    peer_manager: PM,
    logger: L,
    scorer: Option<S>
) -> Selfwhere
    CA::Target: 'static + Access,
    CF::Target: 'static + Filter,
    CW::Target: 'static + Watch<Signer>,
    T::Target: 'static + BroadcasterInterface,
    K::Target: 'static + KeysInterface<Signer = Signer>,
    F::Target: 'static + FeeEstimator,
    L::Target: 'static + Logger,
    P::Target: 'static + Persist<Signer>,
    CMH::Target: 'static + ChannelMessageHandler,
    OMH::Target: 'static + OnionMessageHandler,
    RMH::Target: 'static + RoutingMessageHandler,
    UMH::Target: 'static + CustomMessageHandler,
    PS::Target: 'static + Persister<'a, Signer, CW, T, K, F, L, SC>,

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.

Data Persistence

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 the lightning-persister crate for LDK’s provided implementation.

Persister::persist_graph is responsible for writing out the NetworkGraph to disk, if GossipSync is supplied. See NetworkGraph::write for writing out a NetworkGraph. See the lightning-persister crate for LDK’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.

• P2PGossipSync if given will update the NetworkGraph based on payment failures.

Rapid Gossip Sync

If rapid gossip sync is meant to run at startup, pass RapidGossipSync via gossip_sync to indicate that the BackgroundProcessor should not prune the NetworkGraph instance until the RapidGossipSync instance completes its first sync.

pub fn join(self) -> Result<(), Error>

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.

pub fn stop(self) -> Result<(), Error>

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.

Trait Implementations

impl Drop for BackgroundProcessor

fn drop(&mut self)

Executes the destructor for this type.