Tokio

https://docs.rs/tokio/latest/
Admin
Tokio is an event-driven, non-blocking I/O platform and runtime for writing reliable asynchronous...
Tokens:724,251
Snippets:5,942
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### JoinSet Example Setup

Source: https://docs.rs/tokio/latest/src/tokio/task/join_set.rs.html

Initial boilerplate for spawning multiple tasks and joining them.

```rust
use tokio::task::JoinSet;
use std::time::Duration;
```

--------------------------------

### Write all example

Source: https://docs.rs/tokio/latest/src/tokio/io/util/async_write_ext.rs.html

Example of using write_all to write a byte slice to a file.

```rust
# #[cfg(not(target_family = "wasm"))]
# {
use tokio::io::{self, AsyncWriteExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut file = File::create("foo.txt").await?;

    file.write_all(b"some bytes").await?;
    file.flush().await?;
    Ok(())
}
```

--------------------------------

### Write all buffer example

Source: https://docs.rs/tokio/latest/src/tokio/io/util/async_write_ext.rs.html

Example of using write_all_buf with a File and Cursor.

```rust
# #[cfg(not(target_family = "wasm"))]
# {
use tokio::io::{self, AsyncWriteExt};
use tokio::fs::File;

use std::io::Cursor;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut file = File::create("foo.txt").await?;
    let mut buffer = Cursor::new(b"data to write");

    file.write_all_buf(&mut buffer).await?;
    file.flush().await?;
    Ok(())
}
# }
```

--------------------------------

### Direct Runtime Instance Initialization

Source: https://docs.rs/tokio/latest/src/tokio/runtime/mod.rs.html

Shows the start of a manual Runtime instance configuration.

```rust
# #[cfg(not(target_family = "wasm"))]
# {
use tokio::net::TcpListener;
```

--------------------------------

### Initialize UdpSocket for receiving

Source: https://docs.rs/tokio/latest/src/tokio/net/udp.rs.html

Shows the initial setup for a UDP socket before performing receive operations.

```rust
use tokio::net::UdpSocket;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // Connect to a peer
    let socket = UdpSocket::bind("127.0.0.1:8080").await?;
    socket.connect("127.0.0.1:8081").await?;
```

--------------------------------

### Take Adaptor Example

Source: https://docs.rs/tokio/latest/tokio/io/trait.AsyncReadExt.html

Creates an adaptor that limits the number of bytes read from an AsyncRead source.

```rust
use tokio::io::{self, AsyncReadExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let f = File::open("foo.txt").await?;
    let mut buffer = [0; 5];

    // read at most five bytes
    let mut handle = f.take(5);

    handle.read(&mut buffer).await?;
    Ok(())
}
```

--------------------------------

### Watch Channel Usage Example

Source: https://docs.rs/tokio/latest/src/tokio/sync/watch.rs.html

Demonstrates how to use a watch channel to broadcast updates and process them in a loop.

```rust
use tokio::sync::watch;
use tokio::time::{Duration, sleep};

# async fn dox() -> Result<(), Box<dyn std::error::Error>> {
let (tx, mut rx) = watch::channel("hello");

tokio::spawn(async move {
    // Use the equivalent of a "do-while" loop so the initial value is
    // processed before awaiting the `changed()` future.
    loop {
        println!("{}! ", *rx.borrow_and_update());
        if rx.changed().await.is_err() {
            break;
        }
    }
});

sleep(Duration::from_millis(100)).await;
tx.send("world")?;
# Ok(())
# }
```

--------------------------------

### Creating a New Mutex

Source: https://docs.rs/tokio/latest/src/tokio/sync/mutex.rs.html

Example of initializing a new Mutex instance.

```rust
use tokio::sync::Mutex;

let lock = Mutex::new(5);
```

--------------------------------

### Creating a JoinHandle

Source: https://docs.rs/tokio/latest/src/tokio/runtime/task/join.rs.html

Examples of creating a JoinHandle using spawn and spawn_blocking.

```rust
use tokio::task;

# async fn doc() {
let join_handle: task::JoinHandle<_> = task::spawn(async {
    // some work here
});
# }
```

```rust
use tokio::task;

# async fn doc() {
let join_handle: task::JoinHandle<_> = task::spawn_blocking(|| {
    // some blocking work here
});
# }
```

--------------------------------

### Async IO with UdpSocket

Source: https://docs.rs/tokio/latest/src/tokio/io/async_fd.rs.html

Example demonstrating how to use async_io with a non-blocking UdpSocket to send data.

```rust
use tokio::io::{Interest, unix::AsyncFd};

use std::io;
use std::net::UdpSocket;

#[tokio::main]
async fn main() -> io::Result<()> {
    let socket = UdpSocket::bind("0.0.0.0:8080")?;
    socket.set_nonblocking(true)?;
    let async_fd = AsyncFd::new(socket)?;

    let written = async_fd
        .async_io(Interest::WRITABLE, |inner| inner.send(&[1, 2]))
        .await?;

    println!("wrote {written} bytes");

    Ok(())
}
```

--------------------------------

### Get and Set TTL

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/listener.rs.html

Examples for retrieving and configuring the IP_TTL option on a TCP listener socket.

```rust
use tokio::net::TcpListener;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
   let listener = TcpListener::bind("127.0.0.1:0").await?;

   listener.set_ttl(100).expect("could not set TTL");
   assert_eq!(listener.ttl()?, 100);

   Ok(())
}
```

```rust
use tokio::net::TcpListener;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:0").await?;

    listener.set_ttl(100).expect("could not set TTL");

    Ok(())
}
```

--------------------------------

### Get and Set TTL for UdpSocket

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Examples demonstrating how to retrieve and configure the IP time-to-live (TTL) value for a UDP socket.

```rust
use tokio::net::UdpSocket;

let sock = UdpSocket::bind("127.0.0.1:8080").await?;

println!("{:?}", sock.ttl()?);
```

```rust
use tokio::net::UdpSocket;

let sock = UdpSocket::bind("127.0.0.1:8080").await?;
sock.set_ttl(60)?;
```

--------------------------------

### build

Source: https://docs.rs/tokio/latest/src/tokio/runtime/builder.rs.html

Creates and returns a configured Runtime instance.

```APIDOC
## fn build(&mut self) -> io::Result<Runtime>

### Description
Finalizes the configuration and constructs the Runtime instance, which is then ready to spawn tasks.
```

--------------------------------

### on_thread_start

Source: https://docs.rs/tokio/latest/tokio/runtime/struct.Builder.html

Executes a function after each thread is started but before it starts doing work.

```APIDOC
## pub fn on_thread_start<F>(&mut self, f: F) -> &mut Self

### Description
Executes function f after each thread is started but before it starts doing work. Useful for monitoring.

### Parameters
- **f** (Fn() + Send + Sync + 'static) - Required - The function to execute on thread start.
```

--------------------------------

### Register Thread Start Hook

Source: https://docs.rs/tokio/latest/tokio/runtime/struct.Builder.html

Executes a function when a thread starts.

```rust
let runtime = runtime::Builder::new_multi_thread()
    .on_thread_start(|| {
        println!("thread started");
    })
    .build();
```

--------------------------------

### Create a Named Pipe Server

Source: https://docs.rs/tokio/latest/src/tokio/net/windows/named_pipe.rs.html

Demonstrates how to initialize a server using ServerOptions and create a named pipe instance.

```rust
use tokio::net::windows::named_pipe::ServerOptions;

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-create";

# #[tokio::main] async fn main() -> std::io::Result<()> {
let server = ServerOptions::new().create(PIPE_NAME)?;
# Ok(()) }
```

--------------------------------

### Basic Runtime Usage with tokio::main

Source: https://docs.rs/tokio/latest/src/tokio/runtime/mod.rs.html

Demonstrates using the #[tokio::main] macro to bootstrap an asynchronous TCP echo server.

```rust
# #[cfg(not(target_family = "wasm"))]
# {
use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        let (mut socket, _) = listener.accept().await?;

        tokio::spawn(async move {
            let mut buf = [0; 1024];

            // In a loop, read data from the socket and write the data back.
            loop {
                let n = match socket.read(&mut buf).await {
                    // socket closed
                    Ok(0) => return,
                    Ok(n) => n,
                    Err(e) => {
                        println!("failed to read from socket; err = {:?}", e);
                        return;
                    }
                };

                // Write the data back
                if let Err(e) = socket.write_all(&buf[0..n]).await {
                    println!("failed to write to socket; err = {:?}", e);
                    return;
                }
            }
        });
    }
}
# }
```

--------------------------------

### Create a file with OpenOptions

Source: https://docs.rs/tokio/latest/src/tokio/fs/open_options.rs.html

Configures the file to be created if it does not already exist.

```rust
use tokio::fs::OpenOptions;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let file = OpenOptions::new()
        .write(true)
        .create(true)
        .open("foo.txt")
        .await?;

    Ok(())
}
```

--------------------------------

### Bind and listen using TcpSocket

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/socket.rs.html

Demonstrates how to manually configure a socket with SO_REUSEADDR, bind it to an address, and start listening, equivalent to TcpListener::bind.

```rust
use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    // On platforms with Berkeley-derived sockets, this allows to quickly
    // rebind a socket, without needing to wait for the OS to clean up the
    // previous one.
    //
    // On Windows, this allows rebinding sockets which are actively in use,
    // which allows "socket hijacking", so we explicitly don't set it here.
    // https://docs.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse
    socket.set_reuseaddr(true)?;
    socket.bind(addr)?;

    // Note: the actual backlog used by `TcpListener::bind` is platform-dependent,
    // as Tokio relies on Mio's default backlog value configuration. The `1024` here is only
    // illustrative and does not reflect the real value used.
    let listener = socket.listen(1024)?;
# drop(listener);

    Ok(())
}
```

--------------------------------

### Register a thread start callback

Source: https://docs.rs/tokio/latest/src/tokio/runtime/builder.rs.html

Executes a function when a runtime thread starts, useful for monitoring.

```rust
# #[cfg(not(target_family = "wasm"))]
# {
# use tokio::runtime;
# pub fn main() {
let runtime = runtime::Builder::new_multi_thread()
    .on_thread_start(|| {
        println!("thread started");
    })
    .build();
# }
# }
```

--------------------------------

### SetOnce::new

Source: https://docs.rs/tokio/latest/tokio/sync/struct.SetOnce.html

Creates a new, empty SetOnce instance.

```APIDOC
### Method
`pub fn new() -> SetOnce<T>`

### Description
Creates a new, empty `SetOnce` instance.
```

--------------------------------

### Oneshot Receiver Loop Example

Source: https://docs.rs/tokio/latest/src/tokio/sync/oneshot.rs.html

Example of using a select loop to receive messages from a oneshot channel.

```rust
        msg = &mut recv => {
            println!("Got message: {}", msg.unwrap());
            break;
        }
    }
}
```

--------------------------------

### Blocking on a LocalSet with in-place blocking (Panic Example)

Source: https://docs.rs/tokio/latest/src/tokio/task/local.rs.html

An example of an invalid operation where in-place blocking is attempted within a LocalSet, which will cause a panic.

```rust
use tokio::runtime::Runtime;
use tokio::task;

let rt  = Runtime::new().unwrap();
let local = task::LocalSet::new();
local.block_on(&rt, async {
    let join = task::spawn_local(async {
        let blocking_result = task::block_in_place(|| {
            // ...
        });
        // ...
    });
    join.await.unwrap();
})
```

--------------------------------

### pub fn interval_at(start: Instant, period: Duration) -> Interval

Source: https://docs.rs/tokio/latest/tokio/time/fn.interval_at.html

Creates a new Interval that yields with an interval of period with the first tick completing at start. The default MissedTickBehavior is Burst, which can be configured via set_missed_tick_behavior.

```APIDOC
## Function: interval_at

### Description
Creates a new `Interval` that yields with an interval of `period` with the first tick completing at `start`. The interval will tick indefinitely until dropped.

### Signature
`pub fn interval_at(start: Instant, period: Duration) -> Interval`

### Parameters
- **start** (Instant) - The time at which the first tick completes.
- **period** (Duration) - The duration between subsequent ticks.

### Panics
This function panics if `period` is zero.

### Example
```rust
use tokio::time::{interval_at, Duration, Instant};

let start = Instant::now() + Duration::from_millis(50);
let mut interval = interval_at(start, Duration::from_millis(10));

interval.tick().await; // ticks after 50ms
interval.tick().await; // ticks after 10ms
interval.tick().await; // ticks after 10ms
```
```

--------------------------------

### Initialize runtime with metrics enabled

Source: https://docs.rs/tokio/latest/src/tokio/runtime/metrics/runtime.rs.html

Shows the initial setup required to enable schedule latency histograms before building the runtime.

```rust
use tokio::runtime::{self, Handle};

fn main() {
    runtime::Builder::new_current_thread()
        .enable_metrics_schedule_latency_histogram()
        .build()
```

--------------------------------

### OpenOptions::create()

Source: https://docs.rs/tokio/latest/tokio/fs/struct.OpenOptions.html

Sets the option for creating a new file.

```APIDOC
## pub fn create(&mut self, create: bool) -> &mut OpenOptions

### Description
Sets the option for creating a new file. This option indicates whether a new file will be created if the file does not yet already exist.
```

--------------------------------

### ttl / set_ttl

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Get or set the IP_TTL option.

```APIDOC
## pub fn ttl(&self) -> Result<u32>
## pub fn set_ttl(&self, ttl: u32) -> Result<()>

### Description
Gets or sets the IP_TTL option, which sets the time-to-live field used in every packet sent from this socket.
```

--------------------------------

### Create and write to a file

Source: https://docs.rs/tokio/latest/src/tokio/fs/file.rs.html

Demonstrates creating a new file and writing bytes to it asynchronously using write_all.

```rust
use tokio::fs::File;
use tokio::io::AsyncWriteExt; // for write_all()

# async fn dox() -> std::io::Result<()> {
let mut file = File::create("foo.txt").await?;
file.write_all(b"hello, world!").await?;
# Ok(())
# }
```

--------------------------------

### quickack

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/stream.rs.html

Gets the value of the TCP_QUICKACK option on this socket.

```APIDOC
## fn quickack(&self) -> io::Result<bool>

### Description
Gets the current state of the TCP_QUICKACK option. This is available on Linux, Android, Fuchsia, and Cygwin.
```

--------------------------------

### Creating an RwLock

Source: https://docs.rs/tokio/latest/tokio/sync/struct.RwLock.html

Examples of initializing an RwLock using standard and constant constructors, including variants with reader limits.

```rust
use tokio::sync::RwLock;

let lock = RwLock::new(5);
```

```rust
use tokio::sync::RwLock;

let lock = RwLock::with_max_readers(5, 1024);
```

```rust
use tokio::sync::RwLock;

static LOCK: RwLock<i32> = RwLock::const_new(5);
```

```rust
use tokio::sync::RwLock;

static LOCK: RwLock<i32> = RwLock::const_with_max_readers(5, 1024);
```

--------------------------------

### ttl

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/listener.rs.html

Gets the value of the IP_TTL option for this socket.

```APIDOC
## fn ttl(&self) -> io::Result<u32>

### Description
Gets the current time-to-live (TTL) value for packets sent from this socket.
```

--------------------------------

### BacktraceFrame::symbol_address

Source: https://docs.rs/tokio/latest/tokio/runtime/dump/struct.BacktraceFrame.html

Returns the starting symbol address of the frame.

```APIDOC
### pub fn symbol_address(&self) -> *mut c_void

Returns the starting symbol address of the frame of this function.
```

--------------------------------

### Spawning and running tasks with LocalSet

Source: https://docs.rs/tokio/latest/tokio/task/struct.LocalSet.html

Demonstrates how to spawn tasks onto a LocalSet and drive them to completion using run_until.

```rust
use tokio::task;

let local = task::LocalSet::new();

// Spawn a future on the local set. This future will be run when
// we call `run_until` to drive the task set.
local.spawn_local(async {
    // ...
});

// Run the local task set.
local.run_until(async move {
    // ...
}).await;

// When `run` finishes, we can spawn _more_ futures, which will
// run in subsequent calls to `run_until`.
local.spawn_local(async {
    // ...
});

local.run_until(async move {
    // ...
}).await;
```

--------------------------------

### start_paused

Source: https://docs.rs/tokio/latest/src/tokio/runtime/builder.rs.html

Controls if the runtime's clock starts paused.

```APIDOC
## start_paused(start_paused: bool) -> &mut Self

### Description
Configures whether the runtime's clock starts in a paused state. This requires the current-thread runtime.
```

--------------------------------

### on_thread_start

Source: https://docs.rs/tokio/latest/src/tokio/runtime/builder.rs.html

Registers a function to be executed when a runtime thread starts.

```APIDOC
## fn on_thread_start<F>(&mut self, f: F) -> &mut Self

### Description
Registers a closure to be executed when a runtime thread starts. This is intended for bookkeeping and monitoring use cases.

### Parameters
- **f** (Fn() + Send + Sync + 'static) - Required - The closure to execute when the thread starts.
```

--------------------------------

### Detaching Tasks

Source: https://docs.rs/tokio/latest/src/tokio/runtime/task/join.rs.html

Example of a task being detached by dropping its handle.

```rust
use tokio::task;
use tokio::time;
use std::time::Duration;

# #[tokio::main(flavor = "current_thread")]
# async fn main() {
let original_task = task::spawn(async {
    let _detached_task = task::spawn(async {

```

--------------------------------

### Create directories recursively with tokio::fs::create_dir_all

Source: https://docs.rs/tokio/latest/src/tokio/fs/create_dir_all.rs.html

Demonstrates the basic usage of creating a directory path asynchronously within a Tokio runtime.

```rust
use tokio::fs;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    fs::create_dir_all("/some/dir").await?;
    Ok(())
}
```

--------------------------------

### tos_v4 / set_tos_v4

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Get or set the IP_TOS option for IPv4.

```APIDOC
## pub fn tos_v4(&self) -> Result<u32>
## pub fn set_tos_v4(&self, tos: u32) -> Result<()>

### Description
Gets or sets the IP_TOS option, which sets the type-of-service field used in every packet sent from this socket.
```

--------------------------------

### tclass_v6 / set_tclass_v6

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Get or set the IPV6_TCLASS option for IPv6.

```APIDOC
## pub fn tclass_v6(&self) -> Result<u32>
## pub fn set_tclass_v6(&self, tclass: u32) -> Result<()>

### Description
Gets or sets the IPV6_TCLASS option, specifying the traffic class field used in every packet sent from this socket.
```

--------------------------------

### Create and listen on an IPv6 socket

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/socket.rs.html

Demonstrates initializing a new IPv6 TcpSocket, binding it to an address, and starting a listener.

```rust
use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "[::1]:8080".parse().unwrap();
    let socket = TcpSocket::new_v6()?;
    socket.bind(addr)?;

    let listener = socket.listen(128)?;
# drop(listener);
    Ok(())
}
```

--------------------------------

### Builder::enable_all

Source: https://docs.rs/tokio/latest/tokio/runtime/struct.Builder.html

Enables both I/O and time drivers for the runtime.

```APIDOC
## Builder::enable_all()

### Description
Enables both I/O and time drivers. This is a shorthand for calling `enable_io` and `enable_time` individually.
```

--------------------------------

### multicast_loop_v6 / set_multicast_loop_v6

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Get or set the IPV6_MULTICAST_LOOP option for IPv6.

```APIDOC
## pub fn multicast_loop_v6(&self) -> Result<bool>
## pub fn set_multicast_loop_v6(&self, on: bool) -> Result<()>

### Description
Controls whether this socket sees the multicast packets it sends itself via the IPV6_MULTICAST_LOOP option.
```

--------------------------------

### Accepting connections with UnixListener

Source: https://docs.rs/tokio/latest/src/tokio/net/unix/listener.rs.html

Demonstrates binding a UnixListener to a path and accepting incoming connections in a loop.

```rust
use tokio::net::UnixListener;

#[tokio::main]
async fn main() {
    let listener = UnixListener::bind("/path/to/the/socket").unwrap();
    loop {
        match listener.accept().await {
            Ok((stream, _addr)) => {
                println!("new client!");
            }
            Err(e) => { /* connection failed */ }
        }
    }
}
```

--------------------------------

### multicast_ttl_v4 / set_multicast_ttl_v4

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Get or set the IP_MULTICAST_TTL option for IPv4.

```APIDOC
## pub fn multicast_ttl_v4(&self) -> Result<u32>
## pub fn set_multicast_ttl_v4(&self, ttl: u32) -> Result<()>

### Description
Gets or sets the IP_MULTICAST_TTL option, which indicates the time-to-live value of outgoing multicast packets.
```

--------------------------------

### Build a standard Runtime

Source: https://docs.rs/tokio/latest/src/tokio/runtime/builder.rs.html

Constructs a configured Runtime instance ready for spawning tasks.

```rust
# #[cfg(not(target_family = "wasm"))]
# {
use tokio::runtime::Builder;

let rt  = Builder::new_multi_thread().build().unwrap();

rt.block_on(async {
    println!("Hello from the Tokio runtime");
});
# }
```

--------------------------------

### multicast_loop_v4 / set_multicast_loop_v4

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Get or set the IP_MULTICAST_LOOP option for IPv4.

```APIDOC
## pub fn multicast_loop_v4(&self) -> Result<bool>
## pub fn set_multicast_loop_v4(&self, on: bool) -> Result<()>

### Description
Gets or sets the IP_MULTICAST_LOOP option. If enabled, multicast packets will be looped back to the local socket.
```

--------------------------------

### broadcast / set_broadcast

Source: https://docs.rs/tokio/latest/tokio/net/struct.UdpSocket.html

Get or set the SO_BROADCAST option for the socket.

```APIDOC
## pub fn broadcast(&self) -> Result<bool>
## pub fn set_broadcast(&self, on: bool) -> Result<()>

### Description
Gets or sets the value of the SO_BROADCAST option. When enabled, this socket is allowed to send packets to a broadcast address.
```

--------------------------------

### tokio::main

Source: https://docs.rs/tokio/latest/src/tokio/lib.rs.html

The main macro is used to annotate the entry point of an asynchronous Tokio application, setting up the runtime.

```APIDOC
## #[tokio::main]

### Description
Annotates the main function to run it within a Tokio runtime. This allows the use of .await syntax within the main function.

### Usage
```rust
#[tokio::main]
async fn main() {
    println!("Hello, world!");
}
```
```

--------------------------------

### max_buf_size

Source: https://docs.rs/tokio/latest/tokio/fs/struct.File.html

Gets the maximum buffer size for AsyncRead/AsyncWrite operations.

```APIDOC
## pub fn max_buf_size(&self) -> usize

### Description
Get the maximum buffer size for the underlying AsyncRead / AsyncWrite operation.
```

--------------------------------

### Accepting connections in a loop

Source: https://docs.rs/tokio/latest/tokio/net/struct.TcpListener.html

Demonstrates how to bind a listener and continuously accept incoming connections using a loop.

```rust
use tokio::net::TcpListener;

use std::io;

async fn process_socket<T>(socket: T) {
    // do work with socket here
}

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        let (socket, _) = listener.accept().await?;
        process_socket(socket).await;
    }
}
```

--------------------------------

### Create a new OpenOptions instance

Source: https://docs.rs/tokio/latest/src/tokio/fs/open_options.rs.html

Initializes a new set of options with all flags set to false.

```rust
use tokio::fs::OpenOptions;

let mut options = OpenOptions::new();
let future = options.read(true).open("foo.txt");
```

--------------------------------

### enter

Source: https://docs.rs/tokio/latest/src/tokio/runtime/local_runtime/runtime.rs.html

Enters the runtime context.

```APIDOC
## enter

### Description
Enters the runtime context. This allows you to construct types that must have an executor available on creation, such as Sleep or TcpStream, and allows calling methods like tokio::spawn.

### Signature
`pub fn enter(&self) -> EnterGuard`

### Returns
- **EnterGuard** - A guard that, when dropped, exits the runtime context.
```

--------------------------------

### Handling try_join! results

Source: https://docs.rs/tokio/latest/src/tokio/macros/try_join.rs.html

Example of matching on the result of a try_join! operation.

```rust
match tokio::try_join!(flatten(handle1), flatten(handle2)) {
    Ok(val) => {
        // do something with the values
    }
    Err(err) => {
        println!("Failed with {}.", err);
        # assert_eq!(err, "failed");
    }
}
```

--------------------------------

### Command::new

Source: https://docs.rs/tokio/latest/src/tokio/process/mod.rs.html

Constructs a new Command instance for launching a program at the specified path.

```APIDOC
## Command::new(program: S)

### Description
Constructs a new `Command` for launching the program at `program`. The command defaults to inheriting the current process's environment and working directory.

### Parameters
- **program** (AsRef<OsStr>) - Required - The path or name of the program to execute.
```

--------------------------------

### BufReader::get_pin_mut

Source: https://docs.rs/tokio/latest/tokio/io/struct.BufReader.html

Gets a pinned mutable reference to the underlying reader.

```APIDOC
## pub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut R>

### Description
Gets a pinned mutable reference to the underlying reader. It is inadvisable to directly read from the underlying reader.
```

--------------------------------

### Create a Basic Tokio Runtime

Source: https://docs.rs/tokio/latest/src/tokio/runtime/mod.rs.html

Initializes a new runtime and uses it to spawn a TCP echo server task.

```rust
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::runtime::Runtime;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create the runtime
    let rt  = Runtime::new()?;

    // Spawn the root task
    rt.block_on(async {
        let listener = TcpListener::bind("127.0.0.1:8080").await?;

        loop {
            let (mut socket, _) = listener.accept().await?;

            tokio::spawn(async move {
                let mut buf = [0; 1024];

                // In a loop, read data from the socket and write the data back.
                loop {
                    let n = match socket.read(&mut buf).await {
                        // socket closed
                        Ok(0) => return,
                        Ok(n) => n,
                        Err(e) => {
                            println!("failed to read from socket; err = {:?}", e);
                            return;
                        }
                    };

                    // Write the data back
                    if let Err(e) = socket.write_all(&buf[0..n]).await {
                        println!("failed to write to socket; err = {:?}", e);
                        return;
                    }
                }
            });
        }
    })
}
```

--------------------------------

### Get Last Element

Source: https://docs.rs/tokio/latest/src/tokio/util/linked_list.rs.html

Retrieves the last element of the list if available.

```rust
pub(crate) fn last(&self) -> Option<&L::Target> {
        let tail = self.tail.as_ref()?;
        unsafe { Some(&*tail.as_ptr()) }
    }
```

--------------------------------

### Bind and listen using TcpSocket

Source: https://docs.rs/tokio/latest/tokio/net/struct.TcpSocket.html

Demonstrates how to configure and bind a socket before listening, equivalent to the behavior of TcpListener::bind.

```rust
use tokio::net::TcpSocket;

use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let addr = "127.0.0.1:8080".parse().unwrap();

    let socket = TcpSocket::new_v4()?;
    // On platforms with Berkeley-derived sockets, this allows to quickly
    // rebind a socket, without needing to wait for the OS to clean up the
    // previous one.
    //
    // On Windows, this allows rebinding sockets which are actively in use,
    // which allows "socket hijacking", so we explicitly don't set it here.
    // https://docs.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse
    socket.set_reuseaddr(true)?;
    socket.bind(addr)?;

    // Note: the actual backlog used by `TcpListener::bind` is platform-dependent,
    // as Tokio relies on Mio's default backlog value configuration. The `1024` here is only
    // illustrative and does not reflect the real value used.
    let listener = socket.listen(1024)?;

    Ok(())
}
```

--------------------------------

### Get current instant

Source: https://docs.rs/tokio/latest/src/tokio/time/instant.rs.html

Obtain an Instant representing the current time.

```rust
use tokio::time::Instant;

let now = Instant::now();
```

--------------------------------

### Broadcast Configuration

Source: https://docs.rs/tokio/latest/src/tokio/net/udp.rs.html

Methods to get and set the SO_BROADCAST socket option.

```APIDOC
## fn broadcast(&self) -> io::Result<bool>

### Description
Gets the current value of the SO_BROADCAST option.

## fn set_broadcast(&self, on: bool) -> io::Result<()>

### Description
Sets the SO_BROADCAST option, allowing the socket to send packets to a broadcast address.
```

--------------------------------

### Create a directory asynchronously

Source: https://docs.rs/tokio/latest/src/tokio/fs/create_dir.rs.html

Demonstrates the basic usage of fs::create_dir within a Tokio runtime to create a new directory.

```rust
use tokio::fs;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    fs::create_dir("/some/dir").await?;
    Ok(())
}
```

--------------------------------

### Basic Semaphore Usage

Source: https://docs.rs/tokio/latest/src/tokio/sync/semaphore.rs.html

Demonstrates creating a semaphore, acquiring single and multiple permits, and checking availability.

```rust
use tokio::sync::{Semaphore, TryAcquireError};

# #[tokio::main(flavor = "current_thread")]
# async fn main() {
let semaphore = Semaphore::new(3);

let a_permit = semaphore.acquire().await.unwrap();
let two_permits = semaphore.acquire_many(2).await.unwrap();

assert_eq!(semaphore.available_permits(), 0);

let permit_attempt = semaphore.try_acquire();
assert_eq!(permit_attempt.err(), Some(TryAcquireError::NoPermits));
# }
```

--------------------------------

### Checking for changes

Source: https://docs.rs/tokio/latest/tokio/sync/watch/struct.Receiver.html

Examples demonstrating how to check if a channel has new values or if it has been closed.

```rust
use tokio::sync::watch;

let (tx, mut rx) = watch::channel("hello");

tx.send("goodbye").unwrap();

assert!(rx.has_changed().unwrap());
assert_eq!(*rx.borrow_and_update(), "goodbye");

// The value has been marked as seen
assert!(!rx.has_changed().unwrap());
```

```rust
use tokio::sync::watch;

let (tx, rx) = watch::channel("hello");
tx.send("goodbye").unwrap();

drop(tx);

// The channel is closed
assert!(rx.has_changed().is_err());
```

--------------------------------

### Get raw signal value

Source: https://docs.rs/tokio/latest/src/tokio/signal/unix.rs.html

Retrieve the numeric value of a SignalKind instance.

```rust
# use tokio::signal::unix::SignalKind;
let kind = SignalKind::interrupt();
assert_eq!(kind.as_raw_value(), libc::SIGINT);
```

--------------------------------

### Example of select! with multiple IO types

Source: https://docs.rs/tokio/latest/tokio/macro.select.html

Demonstrates polling multiple tasks using select!, noting that manual management can lead to cancellation safety issues.

```rust
struct File;
struct Channel;
struct Socket;

impl Socket {
    async fn read_packet(&mut self) -> Vec<u8> {
        vec![]
    }
}

async fn read_send(_file: &mut File, _channel: &mut Channel) {
    // do work that is not cancel safe
}

// open our IO types
let mut file = File;
let mut channel = Channel;
let mut socket = Socket;

loop {
    tokio::select! {
        _ = read_send(&mut file, &mut channel) => { /* ... */ },
        _data = socket.read_packet() => { /* ... */ }
        _ = futures::future::ready(()) => break
    }
}
```

--------------------------------

### Get TTL of a TcpStream

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/stream.rs.html

Retrieves the current time-to-live value for the TCP socket.

```rust
```no_run
use tokio::net::TcpStream;

# async fn dox() -> Result<(), Box<dyn std::error::Error>> {
let stream = TcpStream::connect("127.0.0.1:8080").await?;

println!("{:?}", stream.ttl()?);
# Ok(())
# }
```
```

--------------------------------

### Accepting incoming connections

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/listener.rs.html

Demonstrates how to bind a listener and process incoming connections in an asynchronous loop.

```rust
use tokio::net::TcpListener;

use std::io;

async fn process_socket<T>(socket: T) {
    # drop(socket);
    // do work with socket here
}

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        let (socket, _) = listener.accept().await?;
        process_socket(socket).await;
    }
}
```

--------------------------------

### BufReader initialization methods

Source: https://docs.rs/tokio/latest/src/tokio/io/util/buf_reader.rs.html

Methods to create a new BufReader with either default or custom buffer capacity.

```rust
impl<R: AsyncRead> BufReader<R> {
    /// Creates a new `BufReader` with a default buffer capacity. The default is currently 8 KB,
    /// but may change in the future.
    pub fn new(inner: R) -> Self {
        Self::with_capacity(DEFAULT_BUF_SIZE, inner)
    }

    /// Creates a new `BufReader` with the specified buffer capacity.
    pub fn with_capacity(capacity: usize, inner: R) -> Self {
        let buffer = vec![0; capacity];
        Self {
            inner,
            buf: buffer.into_boxed_slice(),
            pos: 0,
            cap: 0,
            seek_state: SeekState::Init,
        }
    }
```

--------------------------------

### Get Linger Duration

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/stream.rs.html

Retrieves the current linger duration for the TCP stream.

```rust
use tokio::net::TcpStream;

# async fn dox() -> Result<(), Box<dyn std::error::Error>> {
let stream = TcpStream::connect("127.0.0.1:8080").await?;

println!("{:?}", stream.linger()?);
# Ok(())
# }
```

--------------------------------

### Get Runtime Name

Source: https://docs.rs/tokio/latest/src/tokio/runtime/handle.rs.html

Retrieves the optional name assigned to the current runtime.

```rust
use tokio::runtime::Handle;

#[tokio::main(flavor = "current_thread", name = "my-runtime")]
async fn main() {
  println!("Current runtime name: {}", Handle::current().name().unwrap());
}
```

--------------------------------

### DirBuilder::new

Source: https://docs.rs/tokio/latest/src/tokio/fs/dir_builder.rs.html

Creates a new instance of DirBuilder with default settings.

```APIDOC
## DirBuilder::new()

### Description
Creates a new set of options with default mode/security settings for all platforms and also non-recursive.

### Signature
`pub fn new() -> Self`
```

--------------------------------

### OpenOptions::new()

Source: https://docs.rs/tokio/latest/tokio/fs/struct.OpenOptions.html

Creates a blank new set of options ready for configuration. All options are initially set to false.

```APIDOC
## pub fn new() -> OpenOptions

### Description
Creates a blank new set of options ready for configuration. All options are initially set to false. This is an async version of std::fs::OpenOptions::new.
```

--------------------------------

### Get Runtime ID

Source: https://docs.rs/tokio/latest/src/tokio/runtime/handle.rs.html

Retrieves the unique identifier for the current runtime instance.

```rust
use tokio::runtime::Handle;

#[tokio::main(flavor = "current_thread")]
async fn main() {
  println!("Current runtime id: {}", Handle::current().id());
}
```

--------------------------------

### device

Source: https://docs.rs/tokio/latest/src/tokio/net/tcp/socket.rs.html

Gets the value for the SO_BINDTODEVICE option on this socket, returning the interface name.

```APIDOC
## fn device(&self) -> io::Result<Option<Vec<u8>>> 

### Description
Gets the value for the SO_BINDTODEVICE option on this socket. This value represents the socket binded device's interface name.
```

--------------------------------

### pub async fn create_dir_all(path: impl AsRef<Path>) -> Result<()>

Source: https://docs.rs/tokio/latest/tokio/fs/fn.create_dir_all.html

Recursively creates a directory and all of its parent components if they are missing. This function is available when the 'fs' feature is enabled.

```APIDOC
## Function: create_dir_all

### Description
Recursively creates a directory and all of its parent components if they are missing. This is an asynchronous version of `std::fs::create_dir_all`.

### Signature
`pub async fn create_dir_all(path: impl AsRef<Path>) -> Result<()>`

### Parameters
- **path** (impl AsRef<Path>) - Required - The path to the directory to be created.

### Errors
- Returns an error if any directory in the path cannot be created.
- If the final component already exists and is a directory, the function returns successfully.
- Concurrent calls to this function are guaranteed not to fail due to race conditions.

### Example
```rust
use tokio::fs;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    fs::create_dir_all("/some/dir").await?;
    Ok(())
}
```
```

--------------------------------

### create

Source: https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.ServerOptions.html

Creates the named pipe server instance.

```APIDOC
## pub fn create(&self, addr: impl AsRef<OsStr>) -> Result<NamedPipeServer>

### Description
Creates the named pipe identified by `addr` for use as a server. This uses the `CreateNamedPipe` function.
```
Tokens:
Raw