},
/// Indicates an outbound payment we made succeeded (ie it made it all the way to its target
/// and we got back the payment preimage for it).
- /// Note that duplicative PaymentSent Events may be generated - it is your responsibility to
- /// deduplicate them by payment_preimage (which MUST be unique)!
PaymentSent {
/// The preimage to the hash given to ChannelManager::send_payment.
/// Note that this serves as a payment receipt, if you wish to have such a thing, you must
},
/// Indicates an outbound payment we made failed. Probably some intermediary node dropped
/// something. You may wish to retry with a different route.
- /// Note that duplicative PaymentFailed Events may be generated - it is your responsibility to
- /// deduplicate them by payment_hash (which MUST be unique)!
PaymentFailed {
/// The hash which was given to ChannelManager::send_payment.
payment_hash: crate::c_types::ThirtyTwoBytes,
/// Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
pub free: Option<extern "C" fn(this_arg: *mut c_void)>,
}
+unsafe impl Send for MessageSendEventsProvider {}
+unsafe impl Sync for MessageSendEventsProvider {}
use lightning::util::events::MessageSendEventsProvider as rustMessageSendEventsProvider;
impl rustMessageSendEventsProvider for MessageSendEventsProvider {
}
}
}
-/// A trait indicating an object may generate events
+/// A trait indicating an object may generate events.
+///
+/// Events are processed by passing an [`EventHandler`] to [`process_pending_events`].
+///
+/// # Requirements
+///
+/// See [`process_pending_events`] for requirements around event processing.
+///
+/// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending
+/// event since the last invocation. The handler must either act upon the event immediately
+/// or preserve it for later handling.
+///
+/// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to
+/// consult the provider's documentation on the implication of processing events and how a handler
+/// may safely use the provider (e.g., see [`ChannelManager::process_pending_events`] and
+/// [`ChainMonitor::process_pending_events`]).
+///
+/// (C-not implementable) As there is likely no reason for a user to implement this trait on their
+/// own type(s).
+///
+/// [`process_pending_events`]: Self::process_pending_events
+/// [`handle_event`]: EventHandler::handle_event
+/// [`ChannelManager::process_pending_events`]: crate::ln::channelmanager::ChannelManager#method.process_pending_events
+/// [`ChainMonitor::process_pending_events`]: crate::chain::chainmonitor::ChainMonitor#method.process_pending_events
#[repr(C)]
pub struct EventsProvider {
/// An opaque pointer which is passed to your function implementations as an argument.
/// This has no meaning in the LDK, and can be NULL or any other value.
pub this_arg: *mut c_void,
- /// Gets the list of pending events which were generated by previous actions, clearing the list
- /// in the process.
- #[must_use]
- pub get_and_clear_pending_events: extern "C" fn (this_arg: *const c_void) -> crate::c_types::derived::CVec_EventZ,
+ /// Processes any events generated since the last call using the given event handler.
+ ///
+ /// Subsequent calls must only process new events. However, handlers must be capable of handling
+ /// duplicate events across process restarts. This may occur if the provider was recovered from
+ /// an old state (i.e., it hadn't been successfully persisted after processing pending events).
+ pub process_pending_events: extern "C" fn (this_arg: *const c_void, handler: crate::lightning::util::events::EventHandler),
/// Frees any resources associated with this object given its this_arg pointer.
/// Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
pub free: Option<extern "C" fn(this_arg: *mut c_void)>,
}
+unsafe impl Send for EventsProvider {}
+unsafe impl Sync for EventsProvider {}
use lightning::util::events::EventsProvider as rustEventsProvider;
-impl rustEventsProvider for EventsProvider {
- fn get_and_clear_pending_events(&self) -> Vec<lightning::util::events::Event> {
- let mut ret = (self.get_and_clear_pending_events)(self.this_arg);
- let mut local_ret = Vec::new(); for mut item in ret.into_rust().drain(..) { local_ret.push( { item.into_native() }); };
- local_ret
+/// Calls the free function if one is set
+#[no_mangle]
+pub extern "C" fn EventsProvider_free(this_ptr: EventsProvider) { }
+impl Drop for EventsProvider {
+ fn drop(&mut self) {
+ if let Some(f) = self.free {
+ f(self.this_arg);
+ }
+ }
+}
+/// A trait implemented for objects handling events from [`EventsProvider`].
+#[repr(C)]
+pub struct EventHandler {
+ /// An opaque pointer which is passed to your function implementations as an argument.
+ /// This has no meaning in the LDK, and can be NULL or any other value.
+ pub this_arg: *mut c_void,
+ /// Handles the given [`Event`].
+ ///
+ /// See [`EventsProvider`] for details that must be considered when implementing this method.
+ pub handle_event: extern "C" fn (this_arg: *const c_void, event: crate::lightning::util::events::Event),
+ /// Frees any resources associated with this object given its this_arg pointer.
+ /// Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
+ pub free: Option<extern "C" fn(this_arg: *mut c_void)>,
+}
+unsafe impl Send for EventHandler {}
+unsafe impl Sync for EventHandler {}
+
+use lightning::util::events::EventHandler as rustEventHandler;
+impl rustEventHandler for EventHandler {
+ fn handle_event(&self, mut event: lightning::util::events::Event) {
+ (self.handle_event)(self.this_arg, crate::lightning::util::events::Event::native_into(event))
}
}
// We're essentially a pointer already, or at least a set of pointers, so allow us to be used
// directly as a Deref trait in higher-level structs:
-impl std::ops::Deref for EventsProvider {
+impl std::ops::Deref for EventHandler {
type Target = Self;
fn deref(&self) -> &Self {
self
}
/// Calls the free function if one is set
#[no_mangle]
-pub extern "C" fn EventsProvider_free(this_ptr: EventsProvider) { }
-impl Drop for EventsProvider {
+pub extern "C" fn EventHandler_free(this_ptr: EventHandler) { }
+impl Drop for EventHandler {
fn drop(&mut self) {
if let Some(f) = self.free {
f(self.this_arg);
projects / ldk-c-bindings / blobdiff