From: Matt Corallo Date: Tue, 12 May 2020 17:48:07 +0000 (-0400) Subject: Add annotations for things which we cannot (yet) expose X-Git-Tag: v0.0.12~30^2~9 X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=5254d6b3d92d3be7869d7b9c6d622fe86222d224;p=rust-lightning Add annotations for things which we cannot (yet) expose --- diff --git a/lightning/src/chain/chaininterface.rs b/lightning/src/chain/chaininterface.rs index 2da2ae8c7..295c337e2 100644 --- a/lightning/src/chain/chaininterface.rs +++ b/lightning/src/chain/chaininterface.rs @@ -226,6 +226,8 @@ impl ChainWatchedUtil { /// parameters with static lifetimes). Other times you can afford a reference, which is more /// efficient, in which case BlockNotifierRef is a more appropriate type. Defining these type /// aliases prevents issues such as overly long function definitions. +/// +/// (C-not exported) as we let clients handle any reference counting they need to do pub type BlockNotifierArc = Arc, C>>; /// BlockNotifierRef is useful when you want a BlockNotifier that points to ChainListeners @@ -273,6 +275,8 @@ impl<'a, CL: Deref + 'a, C: Deref> BlockNotifier<'a, CL, C> /// If the same listener is registered multiple times, unregistering /// will remove ALL occurrences of that listener. Comparison is done using /// the pointer returned by the Deref trait implementation. + /// + /// (C-not exported) because the equality check would always fail pub fn unregister_listener(&self, listener: CL) { let mut vec = self.listeners.lock().unwrap(); // item is a ref to an abstract thing that dereferences to a ChainListener, diff --git a/lightning/src/chain/transaction.rs b/lightning/src/chain/transaction.rs index c4917313f..946562bc1 100644 --- a/lightning/src/chain/transaction.rs +++ b/lightning/src/chain/transaction.rs @@ -35,6 +35,7 @@ impl OutPoint { } /// Converts this OutPoint into the OutPoint field as used by rust-bitcoin + /// (C-not exported) as the same type is used universally in the C bindings for all outpoints pub fn into_bitcoin_outpoint(self) -> BitcoinOutPoint { BitcoinOutPoint { txid: self.txid, diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs index ee99012c5..148fdfa48 100644 --- a/lightning/src/ln/channelmanager.rs +++ b/lightning/src/ln/channelmanager.rs @@ -180,12 +180,15 @@ pub(super) enum HTLCFailReason { } /// payment_hash type, use to cross-lock hop +/// (C-not exported) as we just use [u8; 32] directly #[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)] pub struct PaymentHash(pub [u8;32]); /// payment_preimage type, use to route payment between hop +/// (C-not exported) as we just use [u8; 32] directly #[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)] pub struct PaymentPreimage(pub [u8;32]); /// payment_secret type, use to authenticate sender to the receiver and tie MPP HTLCs together +/// (C-not exported) as we just use [u8; 32] directly #[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)] pub struct PaymentSecret(pub [u8;32]); @@ -2919,6 +2922,7 @@ impl /// If successful, will generate a UpdateHTLCs event, so you should probably poll /// PeerManager::process_events afterwards. /// Note: This API is likely to change! + /// (C-not exported) Cause its doc(hidden) anyway #[doc(hidden)] pub fn update_fee(&self, channel_id: [u8;32], feerate_per_kw: u32) -> Result<(), APIError> { let _ = self.total_consistency_lock.read().unwrap(); @@ -3738,7 +3742,6 @@ pub struct ChannelManagerReadArgs<'a, ChanSigner: 'a + ChannelKeys, M: Deref, T: F::Target: FeeEstimator, L::Target: Logger, { - /// The keys provider which will give us relevant keys. Some keys will be loaded during /// deserialization. pub keys_manager: K, @@ -3775,6 +3778,8 @@ pub struct ChannelManagerReadArgs<'a, ChanSigner: 'a + ChannelKeys, M: Deref, T: /// /// In such cases the latest local transactions will be sent to the tx_broadcaster included in /// this struct. + /// + /// (C-not exported) because we have no HashMap bindings pub channel_monitors: HashMap>, } diff --git a/lightning/src/ln/channelmonitor.rs b/lightning/src/ln/channelmonitor.rs index 4ba7eb2d2..363696443 100644 --- a/lightning/src/ln/channelmonitor.rs +++ b/lightning/src/ln/channelmonitor.rs @@ -180,6 +180,8 @@ impl_writeable!(HTLCUpdate, 0, { payment_hash, payment_preimage, source }); /// /// If you're using this for local monitoring of your own channels, you probably want to use /// `OutPoint` as the key, which will give you a ManyChannelMonitor implementation. +/// +/// (C-not exported) due to an unconstrained generic in `Key` pub struct SimpleManyChannelMonitor where T::Target: BroadcasterInterface, F::Target: FeeEstimator, @@ -1421,6 +1423,8 @@ impl ChannelMonitor { /// Gets a list of txids, with their output scripts (in the order they appear in the /// transaction), which we must learn about spends of via block_connected(). + /// + /// (C-not exported) because we have no HashMap bindings pub fn get_outputs_to_watch(&self) -> &HashMap> { &self.outputs_to_watch } @@ -1429,6 +1433,8 @@ impl ChannelMonitor { /// Generally useful when deserializing as during normal operation the return values of /// block_connected are sufficient to ensure all relevant outpoints are being monitored (note /// that the get_funding_txo outpoint and transaction must also be monitored for!). + /// + /// (C-not exported) as there is no practical way to track lifetimes of returned values. pub fn get_monitored_outpoints(&self) -> Vec<(Txid, u32, &Script)> { let mut res = Vec::with_capacity(self.remote_commitment_txn_on_chain.len() * 2); for (ref txid, &(_, ref outputs)) in self.remote_commitment_txn_on_chain.iter() { diff --git a/lightning/src/ln/features.rs b/lightning/src/ln/features.rs index 8966d8d40..f573ac4c4 100644 --- a/lightning/src/ln/features.rs +++ b/lightning/src/ln/features.rs @@ -279,6 +279,8 @@ mod sealed { /// Tracks the set of features which a node implements, templated by the context in which it /// appears. +/// +/// (C-not exported) as we map the concrete feature types below directly instead pub struct Features { /// Note that, for convenience, flags is LITTLE endian (despite being big-endian on the wire) flags: Vec, diff --git a/lightning/src/ln/msgs.rs b/lightning/src/ln/msgs.rs index 22bca6ee1..22eefb226 100644 --- a/lightning/src/ln/msgs.rs +++ b/lightning/src/ln/msgs.rs @@ -646,6 +646,7 @@ pub enum HTLCFailChannelUpdate { /// As we wish to serialize these differently from Options (Options get a tag byte, but /// OptionalFeild simply gets Present if there are enough bytes to read into it), we have a /// separate enum type for them. +/// (C-not exported) due to a free generic in T #[derive(Clone, PartialEq, Debug)] pub enum OptionalField { /// Optional field is included in message diff --git a/lightning/src/routing/network_graph.rs b/lightning/src/routing/network_graph.rs index 0a779e1e0..1a4a8c1a6 100644 --- a/lightning/src/routing/network_graph.rs +++ b/lightning/src/routing/network_graph.rs @@ -526,13 +526,19 @@ impl fmt::Display for NetworkGraph { impl NetworkGraph { /// Returns all known valid channels' short ids along with announced channel info. + /// + /// (C-not exported) because we have no mapping for `BTreeMap`s pub fn get_channels<'a>(&'a self) -> &'a BTreeMap { &self.channels } /// Returns all known nodes' public keys along with announced node info. + /// + /// (C-not exported) because we have no mapping for `BTreeMap`s pub fn get_nodes<'a>(&'a self) -> &'a BTreeMap { &self.nodes } /// Get network addresses by node id. /// Returns None if the requested node is completely unknown, /// or if node announcement for the node was never received. + /// + /// (C-not exported) as there is no practical way to track lifetimes of returned values. pub fn get_addresses<'a>(&'a self, pubkey: &PublicKey) -> Option<&'a Vec> { if let Some(node) = self.nodes.get(pubkey) { if let Some(node_info) = node.announcement_info.as_ref() { diff --git a/lightning/src/util/logger.rs b/lightning/src/util/logger.rs index 6d42fbf01..acd6d323e 100644 --- a/lightning/src/util/logger.rs +++ b/lightning/src/util/logger.rs @@ -86,6 +86,7 @@ impl Level { /// A Record, unit of logging output with Metadata to enable filtering /// Module_path, file, line to inform on log's source +/// (C-not exported) - we convert to a const char* instead #[derive(Clone,Debug)] pub struct Record<'a> { /// The verbosity level of the message. @@ -102,6 +103,7 @@ pub struct Record<'a> { impl<'a> Record<'a> { /// Returns a new Record. + /// (C-not exported) as fmt can't be used in C #[inline] pub fn new(level: Level, args: fmt::Arguments<'a>, module_path: &'a str, file: &'a str, line: u32) -> Record<'a> { Record { diff --git a/lightning/src/util/ser.rs b/lightning/src/util/ser.rs index a8c3d5621..961d4f102 100644 --- a/lightning/src/util/ser.rs +++ b/lightning/src/util/ser.rs @@ -37,6 +37,8 @@ const MAX_BUF_SIZE: usize = 64 * 1024; /// buffers being written into. /// An impl is provided for any type that also impls std::io::Write which simply ignores size /// hints. +/// +/// (C-not exported) as we only export serialization to/from byte arrays instead pub trait Writer { /// Writes the given buf out. See std::io::Write::write_all for more fn write_all(&mut self, buf: &[u8]) -> Result<(), ::std::io::Error>; @@ -159,6 +161,8 @@ impl Read for ReadTrackingReader { } /// A trait that various rust-lightning types implement allowing them to be written out to a Writer +/// +/// (C-not exported) as we only export serialization to/from byte arrays instead pub trait Writeable { /// Writes self out to the given Writer fn write(&self, writer: &mut W) -> Result<(), ::std::io::Error>; @@ -186,6 +190,8 @@ impl<'a, T: Writeable> Writeable for &'a T { } /// A trait that various rust-lightning types implement allowing them to be read in from a Read +/// +/// (C-not exported) as we only export serialization to/from byte arrays instead pub trait Readable where Self: Sized { @@ -195,6 +201,8 @@ pub trait Readable /// A trait that various higher-level rust-lightning types implement allowing them to be read in /// from a Read given some additional set of arguments which is required to deserialize. +/// +/// (C-not exported) as we only export serialization to/from byte arrays instead pub trait ReadableArgs

where Self: Sized { @@ -203,6 +211,8 @@ pub trait ReadableArgs

} /// A trait that various rust-lightning types implement allowing them to (maybe) be read in from a Read +/// +/// (C-not exported) as we only export serialization to/from byte arrays instead pub trait MaybeReadable where Self: Sized {