Skip to main content

quincy_tun/
lib.rs

1/*!
2# quincy-tun
3
4Cross-platform async TUN library for [Quincy](https://github.com/quincy-rs/quincy).
5
6Forked from [tun-rs](https://github.com/tun-rs/tun-rs) and trimmed to the
7exact surface Quincy needs: an async (tokio) TUN device with optional
8GSO/GRO offload on Linux.
9
10## Supported platforms
11
12Linux, macOS, Windows, FreeBSD, Android, iOS.
13
14## Quick start
15
16```no_run
17# async fn _main() -> std::io::Result<()> {
18use quincy_tun::DeviceBuilder;
19
20let dev = DeviceBuilder::new()
21    .ipv4("10.0.0.1", 24, None)
22    .build_async()?;
23
24let mut buf = vec![0u8; 65536];
25loop {
26    let len = dev.recv(&mut buf).await?;
27    dev.send(&buf[..len]).await?;
28}
29# Ok(()) }
30```
31
32## Linux offload (GSO/GRO)
33
34On Linux, enable TSO/GSO for a 3-4x throughput boost:
35
36```no_run
37# #[cfg(target_os = "linux")]
38# async fn offload_example() -> quincy_tun::Result<()> {
39use quincy_tun::{DeviceBuilder, GROTable, IDEAL_BATCH_SIZE, VIRTIO_NET_HDR_LEN};
40
41let dev = DeviceBuilder::new()
42    .ipv4("10.0.0.1", 24, None)
43    .offload(true)
44    .build_async()?;
45
46let mut original_buffer = vec![0u8; VIRTIO_NET_HDR_LEN + 65535];
47let mut bufs = vec![vec![0u8; 1500]; IDEAL_BATCH_SIZE];
48let mut sizes = vec![0; IDEAL_BATCH_SIZE];
49let mut gro_table = GROTable::default();
50
51let num = dev.recv_multiple(&mut original_buffer, &mut bufs, &mut sizes, 0).await?;
52# Ok(()) }
53```
54*/
55
56pub use crate::builder::*;
57pub use crate::platform::*;
58
59mod async_device;
60mod builder;
61mod error;
62mod platform;
63
64pub use async_device::AsyncDevice;
65pub use error::{Error, Result};
66
67#[cfg(any(
68    target_os = "macos",
69    target_os = "ios",
70    target_os = "tvos",
71    target_os = "freebsd",
72    target_os = "openbsd",
73    target_os = "netbsd",
74))]
75pub(crate) const PACKET_INFORMATION_LENGTH: usize = 4;