Struct lightning_background_processor::BackgroundProcessor

pub struct BackgroundProcessor { /* fields omitted */ }

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 (if a NetGraphMsgHandler 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<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> + Send + Sync, L: 'static + Deref + Send + Sync, P: 'static + Deref + Send + Sync, Descriptor: 'static + SocketDescriptor + Send + Sync, CMH: 'static + Deref + Send + Sync, RMH: 'static + Deref + Send + Sync, EH: 'static + EventHandler + Send, CMP: 'static + Send + ChannelManagerPersister<Signer, CW, T, K, F, L>, 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, NG: 'static + Deref<Target = NetGraphMsgHandler<G, CA, L>> + Send + Sync, UMH: 'static + Deref + Send + Sync, PM: 'static + Deref<Target = PeerManager<Descriptor, CMH, RMH, L, UMH>> + Send + Sync>(
    persister: CMP,
    event_handler: EH,
    chain_monitor: M,
    channel_manager: CM,
    net_graph_msg_handler: Option<NG>,
    peer_manager: PM,
    logger: L
) -> Self where
    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,
    RMH::Target: 'static + RoutingMessageHandler,
    UMH::Target: 'static + CustomMessageHandler, 

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 persist_manager returns an error. In case of an error, the error is retrieved by calling either join or stop.

Data Persistence

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.

Typically, users should either implement ChannelManagerPersister 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.

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.