Skip to content

Commit 2d5a81d

Browse files
committed
Rewrite documentation now that we always use convert_channel_err
Now that we never call `locked_close_channel` directly, the documentation on it should be updated to note that it shouldn't be used, rather relying on `convert_channel_err`, which now gets much of the substantive documentation on closing logic. Similarly, as `finish_close_channel` is now only called from `handle_error` we update the docs on both to note the new semantics.
1 parent e0c3728 commit 2d5a81d

File tree

1 file changed

+17
-20
lines changed

1 file changed

+17
-20
lines changed

lightning/src/ln/channelmanager.rs

Lines changed: 17 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3158,18 +3158,7 @@ macro_rules! handle_error {
31583158
} };
31593159
}
31603160

3161-
/// When a channel is removed, two things need to happen:
3162-
/// (a) This must be called in the same `per_peer_state` lock as the channel-closing action,
3163-
/// (b) [`ChannelManager::finish_close_channel`] needs to be called without holding any locks
3164-
/// (except [`ChannelManager::total_consistency_lock`].
3165-
///
3166-
/// Note that this step can be skipped if the channel was never opened (through the creation of a
3167-
/// [`ChannelMonitor`]/channel funding transaction) to begin with.
3168-
///
3169-
/// For non-coop-close cases, you should generally prefer to call `convert_channel_err` and
3170-
/// [`handle_error`] instead (which delegate to this and [`ChannelManager::finish_close_channel`]),
3171-
/// as they ensure the relevant messages go out as well. In a coop close case, calling this
3172-
/// directly avoids duplicate error messages.
3161+
/// Do not call this directly, use `convert_channel_err` instead.
31733162
#[rustfmt::skip]
31743163
macro_rules! locked_close_channel {
31753164
($self: ident, $chan_context: expr, UNFUNDED) => {{
@@ -3217,7 +3206,18 @@ macro_rules! locked_close_channel {
32173206
}}
32183207
}
32193208

3220-
/// Returns (boolean indicating if we should remove the Channel object from memory, a mapped error)
3209+
/// When a channel is removed, two things need to happen:
3210+
/// (a) This must be called in the same `per_peer_state` lock as the channel-closing action,
3211+
/// (b) [`handle_error`] needs to be called without holding any locks (except
3212+
/// [`ChannelManager::total_consistency_lock`]), which then calls
3213+
/// [`ChannelManager::finish_close_channel`].
3214+
///
3215+
/// Note that this step can be skipped if the channel was never opened (through the creation of a
3216+
/// [`ChannelMonitor`]/channel funding transaction) to begin with.
3217+
///
3218+
/// Returns `(boolean indicating if we should remove the Channel object from memory, a mapped
3219+
/// error)`, except in the `COOP_CLOSE` case, where the bool is elided (it is always implicitly
3220+
/// true).
32213221
#[rustfmt::skip]
32223222
macro_rules! convert_channel_err {
32233223
($self: ident, $peer_state: expr, $err: expr, $chan: expr, $close: expr, $locked_close: expr, $channel_id: expr, _internal) => { {
@@ -4287,13 +4287,10 @@ where
42874287
}
42884288

42894289
/// When a channel is removed, two things need to happen:
4290-
/// (a) [`locked_close_channel`] must be called in the same `per_peer_state` lock as
4291-
/// the channel-closing action,
4292-
/// (b) this needs to be called without holding any locks (except
4293-
/// [`ChannelManager::total_consistency_lock`].
4294-
///
4295-
/// In non-coop-close cases, this is generally accomplished by calling [`convert_channel_err`]
4296-
/// followed by [`handle_error`].
4290+
/// (a) [`convert_channel_err`] must be called in the same `per_peer_state` lock as the
4291+
/// channel-closing action,
4292+
/// (b) [`handle_error`] needs to be called without holding any locks (except
4293+
/// [`ChannelManager::total_consistency_lock`]), which then calls this.
42974294
#[rustfmt::skip]
42984295
fn finish_close_channel(&self, mut shutdown_res: ShutdownResult) {
42994296
debug_assert_ne!(self.per_peer_state.held_by_thread(), LockHeldState::HeldByThread);

0 commit comments

Comments
 (0)