Struct ChanMgr

pub struct ChanMgr<R: Runtime> { /* private fields */ }

An object that remembers a set of live channels, and launches new ones on request.

Use the ChanMgr::get_or_launch function to create a new Channel, or get one if it exists. (For a slightly lower-level API that does no caching, see ChannelFactory and its implementors. For a much lower-level API, see tor_proto::channel::ChannelBuilder.)

Each channel is kept open as long as there is a reference to it, or something else (such as the relay or a network error) kills the channel.

After a ChanMgr launches a channel, it keeps a reference to it until that channel has been unused (that is, had no circuits attached to it) for a certain amount of time. (Currently this interval is chosen randomly from between 180-270 seconds, but this is an implementation detail that may change in the future.)

Implementations

impl<R: Runtime> ChanMgr<R>

pub fn new( runtime: R, config: &ChannelConfig, dormancy: Dormancy, netparams: &NetParameters, memquota: ToplevelAccount, ) -> Self

where R: 'static,

Construct a new channel manager.

A new ChannelAccount will be made from memquota, for each Channel.

The ChannelAccount is used for data associated with this channel.

This does not (currently) include downstream outbound data (ie, data processed by the channel implementation here, awaiting TLS processing and actual transmission). In any case we try to keep those buffers small.

The ChannelAccount does track upstream outbound data (ie, data processed by a circuit, but not yet by the channel), even though that data relates to a specific circuit. TODO #1652 use CircuitAccount for circuit->channel queue.

Usage note

For the manager to work properly, you will need to call ChanMgr::launch_background_tasks.

pub fn launch_background_tasks( self: &Arc<Self>, runtime: &R, netdir: Arc<dyn NetDirProvider>, ) -> Result<Vec<TaskHandle>>

Launch the periodic daemon tasks required by the manager to function properly.

Returns a TaskHandle that can be used to manage those daemon tasks that poll periodically.

pub async fn handle_incoming( &self, src: SocketAddr, stream: <R as NetStreamProvider>::Stream, ) -> Result<Arc<Channel>>

Available on crate feature relay only.

Build a channel for an incoming stream.

The channel may or may not be authenticated. This method will wait until the channel is usable, and may return an error if we already have an existing channel to this peer, or if there are already too many open connections with this peer or subnet (as a dos defence).

pub async fn get_or_launch<T: ChanTarget + ?Sized>( &self, target: &T, usage: ChannelUsage, ) -> Result<(Arc<Channel>, ChanProvenance)>

Try to get a suitable channel to the provided target, launching one if one does not exist.

If there is already a channel launch attempt in progress, this function will wait until that launch is complete, and succeed or fail depending on its outcome.

pub fn bootstrap_events(&self) -> ConnStatusEvents

Return a stream of ConnStatus events to tell us about changes in our ability to connect to the internet.

Note that this stream can be lossy: the caller will not necessarily observe every event on the stream

pub fn expire_channels(&self) -> Duration

Expire all channels that have been unused for too long.

Return the duration from now until next channel expires.

pub fn set_dormancy( &self, dormancy: Dormancy, netparams: Arc<dyn AsRef<NetParameters>>, ) -> StdResult<(), Bug>

Notifies the chanmgr to be dormant like dormancy

pub fn reconfigure( &self, config: &ChannelConfig, how: Reconfigure, netparams: Arc<dyn AsRef<NetParameters>>, ) -> StdResult<(), ReconfigureError>

Reconfigure all channels

pub fn set_pt_mgr(&self, ptmgr: Arc<dyn AbstractPtMgr + 'static>)

Available on crate feature pt-client only.

Replace the transport registry with one that may know about more transports.

Note that the ChannelFactory instances returned by ptmgr are required to time-out channels that take too long to build. You’ll get this behavior by default if the factories implement ChannelFactory using transport::proxied::ExternalProxyPlugin, which tor-ptmgr does.

pub async fn build_unmanaged_channel( &self, target: impl IntoOwnedChanTarget, memquota: ChannelAccount, ) -> Result<Arc<Channel>>

Available on crate feature experimental-api only.

Try to create a new, unmanaged channel to target.

Unlike get_or_launch, this function always creates a new channel, never retries transient failure, and does not register this channel with the ChanMgr.

Generally you should not use this function; get_or_launch is usually a better choice. This function is the right choice if, for whatever reason, you need to manage the lifetime of the channel you create, and make sure that no other code with access to this ChanMgr will be able to use the channel.