X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-c-bindings;a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Flightning%2Futil%2Fevents.rs;h=944d86159ab2a60a847be85c67dda2004a4394a7;hp=43c4db374f8e1c260247cad52790e30fcd2f4d85;hb=4e514def04a4aabea8261173311e6c747d4bd133;hpb=1926a7a71ae0f37ebd6562996769334e0af0cf1b diff --git a/lightning-c-bindings/src/lightning/util/events.rs b/lightning-c-bindings/src/lightning/util/events.rs index 43c4db3..944d861 100644 --- a/lightning-c-bindings/src/lightning/util/events.rs +++ b/lightning-c-bindings/src/lightning/util/events.rs @@ -90,8 +90,6 @@ pub enum Event { }, /// 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 @@ -100,8 +98,6 @@ pub enum Event { }, /// 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, @@ -1059,6 +1055,8 @@ pub struct MessageSendEventsProvider { /// 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, } +unsafe impl Send for MessageSendEventsProvider {} +unsafe impl Sync for MessageSendEventsProvider {} use lightning::util::events::MessageSendEventsProvider as rustMessageSendEventsProvider; impl rustMessageSendEventsProvider for MessageSendEventsProvider { @@ -1087,33 +1085,86 @@ impl Drop 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, } +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 { - 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, +} +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 @@ -1121,8 +1172,8 @@ impl std::ops::Deref for EventsProvider { } /// 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);