Improve docs for ChannelUsage
Try to clarify more that the ChannelUsage is for describing the usage for one particular channel request, not for the channel as a whole. This is a potentially confusing point, so we should spell it out completely.
This commit is contained in:
parent
7715b9c8d6
commit
016a362f8b
|
@ -128,25 +128,33 @@ pub enum Dormancy {
|
|||
Dormant,
|
||||
}
|
||||
|
||||
/// How a channel is going to be used
|
||||
/// The usage that we have in mind when requesting a channel.
|
||||
///
|
||||
/// A channel may be used in multiple ways. Each time it is (re)used, a separate
|
||||
/// ChannelUsage is passed in.
|
||||
/// A channel may be used in multiple ways. Each time a channel is requested
|
||||
/// from `ChanMgr` a separate `ChannelUsage` is passed in to tell the `ChanMgr`
|
||||
/// how the channel will be used this time.
|
||||
///
|
||||
/// To be clear, the `ChannelUsage` is aspect of a _request_ for a channel, and
|
||||
/// is not an immutable property of the channel itself.
|
||||
///
|
||||
/// This type is obtained from a `tor_circmgr::usage::SupportedCircUsage` in
|
||||
/// `tor_circmgr::usage`, and it has roughly the same set of variants.
|
||||
#[derive(Clone, Debug, Copy, Eq, PartialEq)]
|
||||
#[non_exhaustive]
|
||||
pub enum ChannelUsage {
|
||||
/// Use for BEGINDIR-based non-anonymous directory connections
|
||||
/// Requesting a channel to use for BEGINDIR-based non-anonymous directory
|
||||
/// connections.
|
||||
Dir,
|
||||
|
||||
/// Use to transmit user traffic (including exit traffic) over the network.
|
||||
/// Requesting a channel to transmit user traffic (including exit traffic)
|
||||
/// over the network.
|
||||
///
|
||||
/// Includes a circuit being constructed preemptively.
|
||||
/// This includes the case where we are constructing a circuit preemptively,
|
||||
/// and _planning_ to use it for user traffic later on.
|
||||
UserTraffic,
|
||||
|
||||
/// For a channel which is not use for circuit(s), or only for useless circuits
|
||||
/// Requesting a channel that the caller does not plan to used at all, or
|
||||
/// which it plans to use only for testing circuits.
|
||||
UselessCircuit,
|
||||
}
|
||||
|
||||
|
|
Loading…
Reference in New Issue