Структура UnixStream

Подключается к сокету, заданному path.

Эта функция создаёт новый сокет Unix и подключается по указанному пути, связывая возвращаемый поток с дескриптором цикла событий по умолчанию.

Паника

Эта функция вызывает панику, если её вызывают вне среды выполнения с включённым вводом-выводом.

Среда выполнения обычно устанавливается неявно, когда эта функция вызывается из future, выполняемой средой выполнения tokio; в противном случае среду выполнения можно установить явно с помощью функции Runtime::enter.

Подключается к сокету, заданному socket_addr.

Эта функция создаёт новый сокет Unix и подключается по указанному адресу, связывая возвращаемый поток с дескриптором цикла событий по умолчанию.

Паника

Эта функция вызывает панику, если её вызывают вне среды выполнения с включённым вводом-выводом.

Среда выполнения обычно устанавливается неявно, когда эта функция вызывается из future, выполняемой средой выполнения tokio; в противном случае среду выполнения можно установить явно с помощью функции Runtime::enter.

Ожидает наступления любого из запрошенных состояний готовности.

Эту функцию обычно используют вместе с try_read() или try_write(). Она позволяет одновременно читать и записывать данные в один и тот же сокет в одной задаче, не разделяя сокет.

Функция может завершиться, даже если сокет не готов. Это ложное срабатывание, и попытка выполнить операцию вернёт io::ErrorKind::WouldBlock. Функция также может вернуть пустой набор Ready, поэтому всегда проверяйте возвращённое значение и, возможно, ожидайте повторно, если запрошенные состояния не установлены.

Безопасность отмены

Этот метод безопасен при отмене. После наступления события готовности метод будет немедленно возвращать результат до тех пор, пока событие готовности не будет обработано попыткой чтения или записи, завершившейся с WouldBlock или Poll::Pending.

Примеры

Одновременное чтение и запись в поток в одной задаче без разделения.

use tokio::io::Interest;
use tokio::net::UnixStream;
use std::error::Error;
use std::io;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    loop {
        let ready = stream.ready(Interest::READABLE | Interest::WRITABLE).await?;

        if ready.is_readable() {
            let mut data = vec![0; 1024];
            // Try to read data, this may still fail with `WouldBlock`
            // if the readiness event is a false positive.
            match stream.try_read(&mut data) {
                Ok(n) => {
                    println!("read {} bytes", n);
                }
                Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                    continue;
                }
                Err(e) => {
                    return Err(e.into());
                }
            }

        }

        if ready.is_writable() {
            // Try to write data, this may still fail with `WouldBlock`
            // if the readiness event is a false positive.
            match stream.try_write(b"hello world") {
                Ok(n) => {
                    println!("write {} bytes", n);
                }
                Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                    continue;
                }
                Err(e) => {
                    return Err(e.into());
                }
            }
        }
    }
}

Ожидает, пока сокет станет доступен для чтения.

Эта функция эквивалентна ready(Interest::READABLE) и обычно используется вместе с try_read().

Безопасность отмены

Этот метод безопасен при отмене. После наступления события готовности метод будет немедленно возвращать результат до тех пор, пока событие готовности не будет обработано попыткой чтения, завершившейся с WouldBlock или Poll::Pending.

Примеры

use tokio::net::UnixStream;
use std::error::Error;
use std::io;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Connect to a peer
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    let mut msg = vec![0; 1024];

    loop {
        // Wait for the socket to be readable
        stream.readable().await?;

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match stream.try_read(&mut msg) {
            Ok(n) => {
                msg.truncate(n);
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    println!("GOT = {:?}", msg);
    Ok(())
}

Проверяет готовность к чтению.

Если поток Unix в данный момент не готов к чтению, этот метод сохранит копию Waker из предоставленного Context. Когда поток Unix будет готов к чтению, для waker будет вызван Waker::wake.

Обратите внимание: при нескольких вызовах poll_read_ready или poll_read запланировано пробуждение только для Waker из Context, переданного в последнем вызове. (Однако poll_write_ready хранит второй, независимый waker.)

Эта функция предназначена для случаев, когда создать и закрепить future с помощью readable невозможно. По возможности предпочтительно использовать readable, поскольку этот метод поддерживает опрос из нескольких задач одновременно.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если поток Unix не готов к чтению.
• Poll::Ready(Ok(())), если поток Unix готов к чтению.
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может столкнуться с любой стандартной ошибкой ввода-вывода, кроме WouldBlock.

Пытается прочитать данные из потока в предоставленный буфер и возвращает количество прочитанных байтов.

Получает все ожидающие данные из сокета, но не ждёт поступления новых. В случае успеха возвращает количество прочитанных байтов. Поскольку try_read() работает в неблокирующем режиме, буфер не нужно хранить в асинхронной задаче: он может целиком находиться в стеке.

Обычно эта функция используется вместе с readable() или ready().

Возвращаемое значение

Если данные успешно прочитаны, возвращается Ok(n), где n — количество прочитанных байтов. Если n равно 0, это может указывать на один из двух сценариев:

1. Читающая половина потока закрыта и больше не будет выдавать данные.
2. Указанный буфер имеет нулевую длину.

Если поток не готов к чтению данных, возвращается Err(io::ErrorKind::WouldBlock).

Примеры

use tokio::net::UnixStream;
use std::error::Error;
use std::io;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Connect to a peer
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    loop {
        // Wait for the socket to be readable
        stream.readable().await?;

        // Creating the buffer **after** the `await` prevents it from
        // being stored in the async task.
        let mut buf = [0; 4096];

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match stream.try_read(&mut buf) {
            Ok(0) => break,
            Ok(n) => {
                println!("read {} bytes", n);
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Пытается прочитать данные из потока в предоставленные буферы и возвращает количество прочитанных байтов.

Данные копируются в каждый буфер по порядку; последний буфер, в который записываются данные, может быть заполнен лишь частично. Этот метод эквивалентен одному вызову try_read() с объединёнными буферами.

Получает все ожидающие данные из сокета, но не ждёт поступления новых. В случае успеха возвращает количество прочитанных байтов. Поскольку try_read_vectored() работает в неблокирующем режиме, буфер не нужно хранить в асинхронной задаче: он может целиком находиться в стеке.

Обычно эта функция используется вместе с readable() или ready().

Возвращаемое значение

Если данные успешно прочитаны, возвращается Ok(n), где n — количество прочитанных байтов. Ok(0) означает, что читающая половина потока закрыта и больше не будет выдавать данные. Если поток не готов к чтению данных, возвращается Err(io::ErrorKind::WouldBlock).

Примеры

use tokio::net::UnixStream;
use std::error::Error;
use std::io::{self, IoSliceMut};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Connect to a peer
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    loop {
        // Wait for the socket to be readable
        stream.readable().await?;

        // Creating the buffer **after** the `await` prevents it from
        // being stored in the async task.
        let mut buf_a = [0; 512];
        let mut buf_b = [0; 1024];
        let mut bufs = [
            IoSliceMut::new(&mut buf_a),
            IoSliceMut::new(&mut buf_b),
        ];

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match stream.try_read_vectored(&mut bufs) {
            Ok(0) => break,
            Ok(n) => {
                println!("read {} bytes", n);
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Пытается прочитать данные из потока в предоставленный буфер, сдвигая его внутренний курсор, и возвращает количество прочитанных байтов.

Получает все ожидающие данные из сокета, но не ждёт поступления новых. В случае успеха возвращает количество прочитанных байтов. Поскольку try_read_buf() работает в неблокирующем режиме, буфер не нужно хранить в асинхронной задаче: он может целиком находиться в стеке.

Обычно эта функция используется вместе с readable() или ready().

Возвращаемое значение

Если данные успешно прочитаны, возвращается Ok(n), где n — количество прочитанных байтов. Ok(0) означает, что читающая половина потока закрыта и больше не будет выдавать данные. Если поток не готов к чтению данных, возвращается Err(io::ErrorKind::WouldBlock).

Примеры

use tokio::net::UnixStream;
use std::error::Error;
use std::io;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Connect to a peer
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    loop {
        // Wait for the socket to be readable
        stream.readable().await?;

        let mut buf = Vec::with_capacity(4096);

        // Try to read data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match stream.try_read_buf(&mut buf) {
            Ok(0) => break,
            Ok(n) => {
                println!("read {} bytes", n);
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Ожидает, пока сокет не станет доступен для записи.

Эта функция эквивалентна ready(Interest::WRITABLE) и обычно используется вместе с try_write().

Безопасность отмены

Этот метод безопасен при отмене. После возникновения события готовности метод будет немедленно возвращаться, пока попытка записи не завершится ошибкой WouldBlock или Poll::Pending и не обработает это событие.

Примеры

use tokio::net::UnixStream;
use std::error::Error;
use std::io;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Connect to a peer
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    loop {
        // Wait for the socket to be writable
        stream.writable().await?;

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match stream.try_write(b"hello world") {
            Ok(n) => {
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Опрос готовности к записи.

Если Unix-поток в данный момент не готов к записи, этот метод сохранит копию Waker из предоставленного Context. Когда Unix-поток будет готов к записи, для waker будет вызван Waker::wake.

Обратите внимание, что при многократных вызовах poll_write_ready или poll_write пробуждение будет запланировано только для Waker из Context, переданного при последнем вызове. (Однако poll_read_ready хранит второй, независимый waker.)

Эта функция предназначена для случаев, когда невозможно создать и закрепить future с помощью writable. Если возможно, предпочтительно использовать writable, поскольку это позволяет выполнять опрос одновременно из нескольких задач.

Возвращаемое значение

Функция возвращает:

• Poll::Pending, если Unix-поток не готов к записи.
• Poll::Ready(Ok(())), если Unix-поток готов к записи.
• Poll::Ready(Err(e)), если произошла ошибка.

Ошибки

Эта функция может возвращать любые стандартные ошибки ввода-вывода, кроме WouldBlock.

Пытается записать буфер в поток и возвращает количество записанных байтов.

Функция попытается записать всё содержимое buf, однако может быть записана только часть буфера.

Эта функция обычно используется вместе с writable().

Возвращаемое значение

Если данные успешно записаны, возвращается Ok(n), где n — количество записанных байтов. Если поток не готов к записи данных, возвращается Err(io::ErrorKind::WouldBlock).

Примеры

use tokio::net::UnixStream;
use std::error::Error;
use std::io;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Connect to a peer
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    loop {
        // Wait for the socket to be writable
        stream.writable().await?;

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match stream.try_write(b"hello world") {
            Ok(n) => {
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Пытается записать в поток несколько буферов и возвращает количество записанных байтов.

Данные записываются из каждого буфера по порядку; при этом последний буфер может быть прочитан не полностью. Этот метод эквивалентен одному вызову try_write() с объединёнными буферами.

Эта функция обычно используется вместе с writable().

Возвращаемое значение

Если данные успешно записаны, возвращается Ok(n), где n — количество записанных байтов. Если поток не готов к записи данных, возвращается Err(io::ErrorKind::WouldBlock).

Примеры

use tokio::net::UnixStream;
use std::error::Error;
use std::io;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    // Connect to a peer
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");
    let stream = UnixStream::connect(bind_path).await?;

    let bufs = [io::IoSlice::new(b"hello "), io::IoSlice::new(b"world")];

    loop {
        // Wait for the socket to be writable
        stream.writable().await?;

        // Try to write data, this may still fail with `WouldBlock`
        // if the readiness event is a false positive.
        match stream.try_write_vectored(&bufs) {
            Ok(n) => {
                break;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
                continue;
            }
            Err(e) => {
                return Err(e.into());
            }
        }
    }

    Ok(())
}

Пытается выполнить чтение из сокета или запись в него с помощью предоставленной пользователем операции ввода-вывода.

Если сокет готов, вызывается предоставленная замыкающая функция. Она должна попытаться выполнить операцию ввода-вывода над сокетом, вручную вызвав соответствующий системный вызов. Если операция завершается с ошибкой, поскольку сокет на самом деле не готов, замыкающая функция должна вернуть ошибку WouldBlock, а флаг готовности будет сброшен. Затем try_io возвращает значение, полученное от замыкающей функции.

Если сокет не готов, замыкающая функция не вызывается и возвращается ошибка WouldBlock.

Замыкающая функция должна возвращать ошибку WouldBlock только в том случае, если она выполнила операцию ввода-вывода над сокетом, которая завершилась неудачей из-за неготовности сокета. Возврат ошибки WouldBlock в любой другой ситуации приведёт к ошибочному сбросу флага готовности, что может вызвать неправильную работу сокета.

Замыкающая функция не должна выполнять операцию ввода-вывода с помощью методов, определённых для типа Tokio UnixStream, поскольку это нарушит работу флага готовности и может вызвать неправильную работу сокета.

Этот метод не предназначен для использования с объединёнными интересами. Замыкающая функция должна выполнять только один тип операции ввода-вывода, поэтому ей не требуется более одного состояния готовности. При вызове с объединённым интересом этот метод может вызвать панику или ожидать бесконечно.

Обычно вместе с этой функцией используются readable(), writable() или ready().

Читает данные из сокета или записывает их в сокет, используя предоставленную пользователем операцию ввода-вывода.

Ожидается готовность сокета, и, когда сокет готов, вызывается предоставленное замыкание. Замыкание должно попытаться выполнить операцию ввода-вывода с сокетом, вручную вызвав соответствующий системный вызов. Если операция завершается с ошибкой, поскольку сокет фактически не готов, замыкание должно вернуть ошибку WouldBlock. В этом случае флаг готовности сбрасывается, и готовность сокета ожидается снова. Этот цикл повторяется, пока замыкание не вернёт Ok или ошибку, отличную от WouldBlock.

Замыкание должно возвращать ошибку WouldBlock только в том случае, если оно выполнило операцию ввода-вывода с сокетом, завершившуюся неудачей из-за того, что сокет не был готов. Возврат ошибки WouldBlock в любой другой ситуации приведёт к ошибочному сбросу флага готовности, из-за чего сокет может работать неправильно.

Замыкание не должно выполнять операцию ввода-вывода с помощью методов, определённых для типа Tokio UnixStream, поскольку это нарушит работу флага готовности и может привести к неправильной работе сокета.

Этот метод не предназначен для использования с объединёнными интересами. Замыкание должно выполнять только один тип операции ввода-вывода, поэтому ему не должно требоваться более одного состояния готовности. Если вызвать этот метод с объединённым интересом, он может вызвать панику или зависнуть навсегда.

Создаёт новый UnixStream из std::os::unix::net::UnixStream.

Эта функция предназначена для обёртывания UnixStream из стандартной библиотеки в соответствующий тип Tokio.

Примечания

Вызывающий код отвечает за то, чтобы поток был переведён в неблокирующий режим. В противном случае все операции ввода-вывода с потоком будут блокировать поток выполнения, что приведёт к неожиданному поведению. Неблокирующий режим можно установить с помощью set_nonblocking.

Передавать слушатель в блокирующем режиме всегда недопустимо, а поведение в таком случае может измениться в будущем. Например, может возникнуть паника.

Примеры

use tokio::net::UnixStream;
use std::os::unix::net::UnixStream as StdUnixStream;

let std_stream = StdUnixStream::connect("/path/to/the/socket")?;
std_stream.set_nonblocking(true)?;
let stream = UnixStream::from_std(std_stream)?;

Паника

Эта функция вызывает панику, если её вызвать не из среды выполнения с включённым вводом-выводом.

Среда выполнения обычно устанавливается неявно, если эта функция вызвана из future, выполняемой средой выполнения Tokio; в противном случае её можно установить явно с помощью функции Runtime::enter.

Преобразует tokio::net::UnixStream в std::os::unix::net::UnixStream.

Возвращённый std::os::unix::net::UnixStream будет переведён в неблокирующий режим, как true. При необходимости используйте set_nonblocking, чтобы изменить режим блокировки.

Примеры

use std::error::Error;
use std::io::Read;
use tokio::net::UnixListener;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let bind_path = dir.path().join("bind_path");

    let mut data = [0u8; 12];
    let listener = UnixListener::bind(&bind_path)?;
    let (tokio_unix_stream, _) = listener.accept().await?;
    let mut std_unix_stream = tokio_unix_stream.into_std()?;
    std_unix_stream.set_nonblocking(false)?;
    std_unix_stream.read_exact(&mut data)?;
    Ok(())
}

Создаёт безымянную пару соединённых сокетов.

Эта функция создаёт пару взаимосвязанных сокетов Unix для двустороннего обмена данными. Каждый сокет будет связан с дескриптором цикла обработки событий по умолчанию.

Возвращает адрес сокета локальной стороны этого соединения.

Примеры

use tokio::net::UnixStream;

let dir = tempfile::tempdir().unwrap();
let bind_path = dir.path().join("bind_path");
let stream = UnixStream::connect(bind_path).await?;

println!("{:?}", stream.local_addr()?);

Возвращает адрес сокета удалённой стороны этого соединения.

Примеры

use tokio::net::UnixStream;

let dir = tempfile::tempdir().unwrap();
let bind_path = dir.path().join("bind_path");
let stream = UnixStream::connect(bind_path).await?;

println!("{:?}", stream.peer_addr()?);

Возвращает эффективные учётные данные процесса, вызвавшего connect или pair.

Возвращает значение параметра SO_ERROR.

Разделяет UnixStream на читающую и записывающую половины, которые можно использовать для одновременного чтения из потока и записи в него.

Этот метод эффективнее, чем into_split, но половины нельзя переместить в независимо запущенные задачи.

Разделяет UnixStream на читающую и записывающую половины, которые можно использовать для одновременного чтения из потока и записи в него.

В отличие от split, принадлежащие вызывающему половины можно переместить в отдельные задачи, однако это требует выделения памяти в куче.

Примечание: При удалении записывающей половины будет закрыта только записывающая сторона потока. Это эквивалентно вызову shutdown() для UnixStream.

Потребляет поток и возвращает объект ввода-вывода tokio.

Это эквивалентно UnixStream::from_std(stream).

Возвращает аргумент без изменений.

Вызывает U::from(self).

То есть это преобразование выполняется так, как решит реализация From<T> for U.