Struct DataStream

pub struct DataStream { /* private fields */ }

An anonymized stream over the Tor network.

For most purposes, you can think of this type as an anonymized TCP stream: it can read and write data, and get closed when it’s done.

DataStream implements [futures::io::AsyncRead] and [futures::io::AsyncWrite], so you can use it anywhere that those traits are expected.

Examples

Connecting to an HTTP server and sending a request, using AsyncWriteExt::write_all:

let mut stream = tor_client.connect(("icanhazip.com", 80), None).await?;

use futures::io::AsyncWriteExt;

stream
    .write_all(b"GET / HTTP/1.1\r\nHost: icanhazip.com\r\nConnection: close\r\n\r\n")
    .await?;

// Flushing the stream is important; see below!
stream.flush().await?;

Reading the result, using AsyncReadExt::read_to_end:

use futures::io::AsyncReadExt;

let mut buf = Vec::new();
stream.read_to_end(&mut buf).await?;

println!("{}", String::from_utf8_lossy(&buf));

Usage with Tokio

If the tokio crate feature is enabled, this type also implements tokio::io::AsyncRead and tokio::io::AsyncWrite for easier integration with code that expects those traits.

Remember to call flush!

DataStream buffers data internally, in order to write as few cells as possible onto the network. In order to make sure that your data has actually been sent, you need to make sure that [AsyncWrite::poll_flush] runs to completion: probably via AsyncWriteExt::flush.

Splitting the type

This type is internally composed of a DataReader and a DataWriter; the DataStream::split method can be used to split it into those two parts, for more convenient usage with e.g. stream combinators.

How long does a stream live?

A DataStream will live until all references to it are dropped, or until it is closed explicitly.

If you split the stream into a DataReader and a DataWriter, it will survive until both are dropped, or until it is closed explicitly.

A stream can also close because of a network error, or because the other side of the stream decided to close it.

Implementations

impl DataStream

pub fn split(self) -> (DataReader, DataWriter)

Divide this DataStream into its constituent parts.

pub async fn wait_for_connection(&mut self) -> Result<(), Error>

Wait until a CONNECTED cell is received, or some other cell is received to indicate an error.

Does nothing if this stream is already connected.

pub fn circuit(&self) -> &ClientCirc

Available on crate feature experimental-api only.

Return a reference to this stream’s circuit?

This is an experimental API; it is not covered by semver guarantee. It is likely to change or disappear in a future release.

TODO: Should there be an AttachedToCircuit trait that we use for all client stream types? Should this return an Option<&ClientCirc>?

TODO RPC: Perhaps we should deprecate this in favor of stream.ctrl().circuit().

pub fn ctrl(&self) -> &Arc<DataStreamCtrl>

Available on crate feature stream-ctrl only.

Return a DataStreamCtrl object that can be used to monitor and interact with this stream without holding the stream itself.

Trait Implementations

impl AsyncRead for DataStream

fn poll_read( self: Pin<&mut DataStream>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for DataStream

Available on crate feature tokio only.

fn poll_read( self: Pin<&mut DataStream>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<(), Error>>

Attempts to read from the AsyncRead into buf.

impl AsyncWrite for DataStream

fn poll_write( self: Pin<&mut DataStream>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from buf into the object.

fn poll_flush( self: Pin<&mut DataStream>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close( self: Pin<&mut DataStream>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempt to close the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl AsyncWrite for DataStream

Available on crate feature tokio only.

fn poll_write( self: Pin<&mut DataStream>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from buf into the object.

fn poll_flush( self: Pin<&mut DataStream>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown( self: Pin<&mut DataStream>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Debug for DataStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.