Struct AsyncDevice

Source

pub struct AsyncDevice(/* private fields */);

Available on Unix and non-macOS only.

Expand description

An async Tun/Tap device wrapper around a Tun/Tap device.

This type does not provide a split method, because this functionality can be achieved by instead wrapping the socket in an Arc.

§Streams

If you need to produce a Stream, you can look at DeviceFramed.

Note: DeviceFramed is only available when the async_framed feature is enabled.

§Examples

use tun_rs::{AsyncDevice, DeviceBuilder};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Create a TUN device with basic configuration
    let dev = DeviceBuilder::new()
        .name("tun0")
        .mtu(1500)
        .ipv4("10.0.0.1", "255.255.255.0", None)
        .build_async()?;

    // Send a simple packet (Replace with real IP message)
    let packet = b"[IP Packet: 10.0.0.1 -> 10.0.0.2] Hello, Async TUN!";
    dev.send(packet).await?;

    // Receive a packet
    let mut buf = [0u8; 1500];
    let n = dev.recv(&mut buf).await?;
    println!("Received {} bytes: {:?}", n, &buf[..n]);

    Ok(())
}

Implementations§

Source §

impl AsyncDevice

Source

pub fn poll_readable(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Available on crate features async_io or async_tokio only.

Polls the I/O handle for readability.

§Caveats

Note that on multiple calls to a poll_* method in the recv direction, only the Waker from the Context passed to the most recent call will be scheduled to receive a wakeup.

§Return value

The function returns:

Poll::Pending if the device is not ready for reading.
Poll::Ready(Ok(())) if the device is ready for reading.
Poll::Ready(Err(e)) if an error is encountered.

§Errors

This function may encounter any standard I/O error except WouldBlock.

Source

pub fn poll_recv( &self, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Available on crate features async_io or async_tokio only.

Attempts to receive a single packet from the device

§Caveats

Note that on multiple calls to a poll_* method in the recv direction, only the Waker from the Context passed to the most recent call will be scheduled to receive a wakeup.

§Return value

The function returns:

Poll::Pending if the device is not ready to read
Poll::Ready(Ok(())) reads data buf if the device is ready
Poll::Ready(Err(e)) if an error is encountered.

§Errors

This function may encounter any standard I/O error except WouldBlock.

Source

pub fn poll_writable(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Available on crate features async_io or async_tokio only.

Polls the I/O handle for writability.

§Caveats

Note that on multiple calls to a poll_* method in the send direction, only the Waker from the Context passed to the most recent call will be scheduled to receive a wakeup.

§Return value

The function returns:

Poll::Pending if the device is not ready for writing.
Poll::Ready(Ok(())) if the device is ready for writing.
Poll::Ready(Err(e)) if an error is encountered.

§Errors

This function may encounter any standard I/O error except WouldBlock.

Source

pub fn poll_send(&self, cx: &mut Context<'_>, buf: &[u8]) -> Poll<Result<usize>>

Available on crate features async_io or async_tokio only.

Attempts to send packet to the device

§Caveats

Note that on multiple calls to a poll_* method in the send direction, only the Waker from the Context passed to the most recent call will be scheduled to receive a wakeup.

§Return value

The function returns:

Poll::Pending if the device is not available to write
Poll::Ready(Ok(n)) n is the number of bytes sent
Poll::Ready(Err(e)) if an error is encountered.

§Errors

This function may encounter any standard I/O error except WouldBlock.

Source §

impl AsyncDevice

Source

pub fn new(device: SyncDevice) -> Result<AsyncDevice>

Available on crate features async_io or async_tokio only.

Source

pub unsafe fn from_fd(fd: RawFd) -> Result<AsyncDevice>

Available on crate features async_io or async_tokio only.

§Safety

This method is safe if the provided fd is valid Construct a AsyncDevice from an existing file descriptor

Source

pub fn into_fd(self) -> Result<RawFd>

Available on crate features async_io or async_tokio only.

Source

pub async fn readable(&self) -> Result<()>

Available on crate features async_io or async_tokio only.

Waits for the device to become readable.

This function is usually paired with try_recv().

The function may complete without the device being readable. This is a false-positive and attempting a try_recv() will return with io::ErrorKind::WouldBlock.

§Cancel safety

This method is cancel safe. Once a readiness event occurs, the method will continue to return immediately until the readiness event is consumed by an attempt to read that fails with WouldBlock or Poll::Pending.

Source

pub async fn writable(&self) -> Result<()>

Available on crate features async_io or async_tokio only.

Waits for the device to become writable.

This function is usually paired with try_send().

The function may complete without the device being writable. This is a false-positive and attempting a try_send() will return with io::ErrorKind::WouldBlock.

§Cancel safety

This method is cancel safe. Once a readiness event occurs, the method will continue to return immediately until the readiness event is consumed by an attempt to write that fails with WouldBlock or Poll::Pending.

Source

pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>

Available on crate features async_io or async_tokio only.

Receives a single packet from the device. On success, returns the number of bytes read.

The function must be called with valid byte array buf of sufficient size to hold the message bytes. If a message is too long to fit in the supplied buffer, excess bytes may be discarded.

Source

pub fn try_recv(&self, buf: &mut [u8]) -> Result<usize>

Available on crate features async_io or async_tokio only.

Tries to receive a single packet from the device. On success, returns the number of bytes read.

This method must be called with valid byte array buf of sufficient size to hold the message bytes. If a message is too long to fit in the supplied buffer, excess bytes may be discarded.

When there is no pending data, Err(io::ErrorKind::WouldBlock) is returned. This function is usually paired with readable().

Source

pub async fn send(&self, buf: &[u8]) -> Result<usize>

Available on crate features async_io or async_tokio only.

Send a packet to the device

§Return

On success, the number of bytes sent is returned, otherwise, the encountered error is returned.

Source

pub fn try_send(&self, buf: &[u8]) -> Result<usize>

Available on crate features async_io or async_tokio only.

Tries to send packet to the device.

When the device buffer is full, Err(io::ErrorKind::WouldBlock) is returned. This function is usually paired with writable().

§Returns

If successful, Ok(n) is returned, where n is the number of bytes sent. If the device is not ready to send data, Err(ErrorKind::WouldBlock) is returned.

Source