Struct tor_proto::stream::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.

Implementations

impl DataStream

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

Divide this DataStream into its constituent parts.

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

Available on crate feature tokio only.

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

Attempts to read from the AsyncRead into buf.

impl AsyncRead for DataStream

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

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 AsyncWrite for DataStream

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

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<IoResult<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<IoResult<()>>

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 Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<IoResult<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<IoResult<()>>

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

fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<IoResult<()>>

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

Formats the value using the given formatter.