unisock 1.0.0

Unified socket with different implementations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

//! Socket with custom implementations.
//!
//! This crate provides the core API for using custom implementations of sockets.

#![no_std]

use core::{future::Future, net::SocketAddr};

/// Asynchronous socket backend that provides fundamental components of a connection type.
pub trait AsyncBackend {
    /// The error type that is returned by the backend.
    type Error;

    /// The listener type that is used to accept incoming connections.
    type Listener<'a>: AsyncListener<Connection<'a> = Self::Connection<'a>, Error = Self::Error>
    where
        Self: 'a;

    /// The connection type that is used to send and receive data.
    type Connection<'a>: AsyncConnection<Error = Self::Error>
    where
        Self: 'a;

    /// Binds the socket to the specified address and returns the socket.
    fn bind(addr: SocketAddr) -> Result<Self, Self::Error>
    where
        Self: Sized;

    /// The connection type that is used to send and receive data.
    fn listen(&self) -> Result<Self::Listener<'_>, Self::Error>;

    /// Connects to a remote address and returns the connection.
    fn connect(
        &self,
        addr: SocketAddr,
    ) -> impl Future<Output = Result<Self::Connection<'_>, Self::Error>> + '_;
}

/// Asynchronous listener that accepts incoming connections.
pub trait AsyncListener {
    /// The error type that is returned by the listener.
    type Error;

    /// The connection type that is accepted by the listener.
    type Connection<'a>: AsyncConnection<Error = Self::Error>
    where
        Self: 'a;

    /// Accepts a new connection on the listener. On success, returns the connection and the
    /// remote address.
    fn accept(
        &self,
    ) -> impl Future<Output = Result<(Self::Connection<'_>, SocketAddr), Self::Error>> + '_;

    /// Closes the listener.
    fn close(self) -> impl Future<Output = Result<(), Self::Error>>;
}

/// Asynchronous connection that provides the basic API for sending and receiving data.
pub trait AsyncConnection {
    /// The error type that is returned by the connection.
    type Error;

    /// Receives a single datagram message on the socket. On success, returns the number of bytes read.
    fn read<'fut>(
        &'fut mut self,
        buf: &'fut mut [u8],
    ) -> impl Future<Output = Result<usize, Self::Error>> + 'fut;

    /// Sends data on the socket. On success, returns the number of bytes written.
    fn write<'fut>(
        &'fut mut self,
        buf: &'fut [u8],
    ) -> impl Future<Output = Result<usize, Self::Error>> + 'fut;

    /// Polls the I/O handle for readability.
    fn poll_readable(&self, cx: &mut core::task::Context<'_>) -> bool;

    /// Polls the I/O handle for writeability.
    fn poll_writable(&self, cx: &mut core::task::Context<'_>) -> bool;

    /// Closes the connection.
    fn close(self) -> impl Future<Output = Result<(), Self::Error>>;
}