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=4dcbd81fee8ce51b96aeb9be6aa1f55076b91474;hb=4e514def04a4aabea8261173311e6c747d4bd133;hpb=5eebd45b471833805e81ad4c23ec93d7711e0a23 diff --git a/lightning-c-bindings/src/lightning/util/events.rs b/lightning-c-bindings/src/lightning/util/events.rs index 4dcbd81..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, @@ -148,14 +144,14 @@ impl Event { Event::PaymentReceived {ref payment_hash, ref payment_preimage, ref payment_secret, ref amt, ref user_payment_id, } => { let mut payment_hash_nonref = (*payment_hash).clone(); let mut payment_preimage_nonref = (*payment_preimage).clone(); - let mut local_payment_preimage_nonref = if payment_preimage_nonref.data == [0; 32] { None } else { Some( { ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage_nonref.data) }) }; + let mut local_payment_preimage_nonref = if payment_preimage_nonref.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentPreimage(payment_preimage_nonref.data) }) }; let mut payment_secret_nonref = (*payment_secret).clone(); let mut amt_nonref = (*amt).clone(); let mut user_payment_id_nonref = (*user_payment_id).clone(); nativeEvent::PaymentReceived { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash_nonref.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash_nonref.data), payment_preimage: local_payment_preimage_nonref, - payment_secret: ::lightning::ln::channelmanager::PaymentSecret(payment_secret_nonref.data), + payment_secret: ::lightning::ln::PaymentSecret(payment_secret_nonref.data), amt: amt_nonref, user_payment_id: user_payment_id_nonref, } @@ -163,14 +159,14 @@ impl Event { Event::PaymentSent {ref payment_preimage, } => { let mut payment_preimage_nonref = (*payment_preimage).clone(); nativeEvent::PaymentSent { - payment_preimage: ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage_nonref.data), + payment_preimage: ::lightning::ln::PaymentPreimage(payment_preimage_nonref.data), } }, Event::PaymentFailed {ref payment_hash, ref rejected_by_dest, } => { let mut payment_hash_nonref = (*payment_hash).clone(); let mut rejected_by_dest_nonref = (*rejected_by_dest).clone(); nativeEvent::PaymentFailed { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash_nonref.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash_nonref.data), rejected_by_dest: rejected_by_dest_nonref, } }, @@ -201,23 +197,23 @@ impl Event { } }, Event::PaymentReceived {mut payment_hash, mut payment_preimage, mut payment_secret, mut amt, mut user_payment_id, } => { - let mut local_payment_preimage = if payment_preimage.data == [0; 32] { None } else { Some( { ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage.data) }) }; + let mut local_payment_preimage = if payment_preimage.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentPreimage(payment_preimage.data) }) }; nativeEvent::PaymentReceived { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash.data), payment_preimage: local_payment_preimage, - payment_secret: ::lightning::ln::channelmanager::PaymentSecret(payment_secret.data), + payment_secret: ::lightning::ln::PaymentSecret(payment_secret.data), amt: amt, user_payment_id: user_payment_id, } }, Event::PaymentSent {mut payment_preimage, } => { nativeEvent::PaymentSent { - payment_preimage: ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage.data), + payment_preimage: ::lightning::ln::PaymentPreimage(payment_preimage.data), } }, Event::PaymentFailed {mut payment_hash, mut rejected_by_dest, } => { nativeEvent::PaymentFailed { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash.data), rejected_by_dest: rejected_by_dest, } }, @@ -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);