Struct DeviceFramed 

pub struct DeviceFramed<C, T = AsyncDevice> { /* private fields */ }

Available on (crate features async_io or async_tokio) and crate feature async_framed only.

A unified Stream and Sink interface over an AsyncDevice, using Encoder and Decoder traits to frame packets as higher-level messages.

Raw device interfaces (such as TUN/TAP) operate on individual packets, but higher-level protocols often work with logical frames. This struct provides an abstraction layer that decodes incoming packets into frames, and encodes outgoing frames into packet buffers.

On Linux, this struct also supports Generic Segmentation Offload (GSO) for sending and Generic Receive Offload (GRO) for receiving, allowing multiple small packets to be aggregated or split transparently for performance optimization.

This struct combines both reading and writing into a single object. If separate control over read/write is needed, consider calling .split() to obtain DeviceFramedRead and DeviceFramedWrite separately.

You can also create multiple independent framing streams using: DeviceFramed::new(dev.clone(), BytesCodec::new()), with the device wrapped in Arc<AsyncDevice>.

A unified async read/write interface for TUN/TAP devices using framed I/O

Combines an async device with a codec to provide Stream and Sink implementations for reading and writing framed packets.

Examples

Basic usage with BytesCodec

use bytes::BytesMut;
use futures::{SinkExt, StreamExt};
use tun_rs::async_framed::{BytesCodec, DeviceFramed};
use tun_rs::DeviceBuilder;

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

    // Create a framed device with BytesCodec
    let mut framed = DeviceFramed::new(dev, BytesCodec::new());

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

    // Receive frames
    while let Some(frame) = framed.next().await {
        match frame {
            Ok(bytes) => println!("Received: {:?}", bytes),
            Err(e) => eprintln!("Error receiving frame: {}", e),
        }
    }
    Ok(())
}

Implementations

impl<C, T> DeviceFramed<C, T>

where T: Borrow<AsyncDevice>,

pub fn new(dev: T, codec: C) -> DeviceFramed<C, T>

Construct from a AsyncDevice with a specific codec

pub fn read_buffer_size(&self) -> usize

pub fn write_buffer_size(&self) -> usize

pub fn set_read_buffer_size(&mut self, read_buffer_size: usize)

Sets the size of the read buffer in bytes.

Must be at least as large as the MTU to ensure complete packet reception.

pub fn set_write_buffer_size(&mut self, write_buffer_size: usize)

Sets the size of the write buffer in bytes.

On Linux, if GSO (Generic Segmentation Offload) is enabled, this setting is ignored, and the send buffer size is fixed to a larger value to accommodate large TCP segments.

If the current buffer size is already greater than or equal to the requested size, this call has no effect.

Parameters

• write_buffer_size: Desired size in bytes for the write buffer.

pub fn read_buffer(&self) -> &BytesMut

Returns a reference to the read buffer.

pub fn read_buffer_mut(&mut self) -> &mut BytesMut

Returns a mutable reference to the read buffer.

pub fn into_inner(self) -> T

Consumes the Framed, returning its underlying I/O stream.

impl<C, T> DeviceFramed<C, T>

where T: Borrow<AsyncDevice> + Clone, C: Clone,

pub fn split(self) -> (DeviceFramedRead<C, T>, DeviceFramedWrite<C, T>)

Split the framed device to read-half and write-half

Example

use std::net::Ipv4Addr;
use std::sync::Arc;
use tun_rs::{
    async_framed::{BytesCodec, DeviceFramed},
    DeviceBuilder,
};
let dev = Arc::new(
    DeviceBuilder::new()
        .ipv4(Ipv4Addr::new(10, 0, 0, 21), 24, None)
        .build_async()?,
);
let (r, w) = DeviceFramed::new(dev, BytesCodec::new()).split();

Trait Implementations

impl<I, C, T> Sink<I> for DeviceFramed<C, T>

where T: Borrow<AsyncDevice>, C: Encoder<I>,

type Error = <C as Encoder<I>>::Error

The type of value produced by the sink when an error occurs.

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

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, item: I) -> Result<(), Self::Error>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

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

Flush any remaining output from this sink.

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

Flush any remaining output and close this sink, if necessary.

impl<C, T> Stream for DeviceFramed<C, T>

where T: Borrow<AsyncDevice>, C: Decoder,

type Item = Result<<C as Decoder>::Item, <C as Decoder>::Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<C, T> Unpin for DeviceFramed<C, T>