tcplane 8.1.0

tcplane is a lightweight and high-performance Rust TCP server library designed to simplify network service development. It supports TCP communication, data stream management, and connection handling, focusing on providing efficient low-level network connections and data transmission capabilities, making it ideal for building modern network services.
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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

use crate::*;

impl ArcRwLockStream {
    /// Creates a new `ArcRwLockStream` from an existing `Arc<RwLock<TcpStream>>`.
    ///
    /// # Arguments
    ///
    /// - `ArcRwLock<TcpStream>` - The Arc-wrapped RwLock containing the TCP stream.
    ///
    /// # Returns
    ///
    /// - `Self` - A new ArcRwLockStream instance.
    pub fn from(arc_rw_lock_stream: ArcRwLock<TcpStream>) -> Self {
        Self(arc_rw_lock_stream)
    }

    /// Creates a new `ArcRwLockStream` from a raw `TcpStream`.
    ///
    /// # Arguments
    ///
    /// - `TcpStream` - The TCP stream to wrap.
    ///
    /// # Returns
    ///
    /// - `Self` - A new ArcRwLockStream instance.
    pub fn from_stream(stream: TcpStream) -> Self {
        Self(Arc::new(RwLock::new(stream)))
    }

    /// Acquires a read lock on the inner TCP stream.
    ///
    /// # Returns
    ///
    /// - `ArcRwLockReadGuard<'_, TcpStream>` - A read guard for the TCP stream.
    pub async fn read(&self) -> ArcRwLockReadGuard<'_, TcpStream> {
        self.0.read().await
    }

    /// Acquires a write lock on the inner TCP stream.
    ///
    /// # Returns
    ///
    /// - `ArcRwLockWriteGuard<'_, TcpStream>` - A write guard for the TCP stream.
    pub async fn write(&self) -> ArcRwLockWriteGuard<'_, TcpStream> {
        self.0.write().await
    }

    /// Attempts to send data through the stream.
    ///
    /// # Arguments
    ///
    /// - `D` - Data that can be converted to a byte slice.
    ///
    /// # Returns
    ///
    /// - `ResponseResult` - Ok(()) on success, or an error on failure.
    pub async fn try_send<D>(&self, data: D) -> ResponseResult
    where
        D: AsRef<[u8]>,
    {
        let mut stream: ArcRwLockWriteGuard<'_, TcpStream> = self.write().await;
        stream
            .write_all(data.as_ref())
            .await
            .map_err(|e| ResponseError::WriteError(e.to_string()))?;
        Ok(())
    }

    /// Sends data through the stream.
    ///
    /// # Arguments
    ///
    /// - `D` - Data that can be converted to a byte slice.
    ///
    /// # Panics
    ///
    /// Panics if the write operation fails.
    pub async fn send<D>(&self, data: D)
    where
        D: AsRef<[u8]>,
    {
        self.try_send(data).await.unwrap();
    }

    /// Attempts to flush the stream.
    ///
    /// # Returns
    ///
    /// - `ResponseResult` - Ok(()) on success, or an error on failure.
    pub async fn try_flush(&self) -> ResponseResult {
        let mut stream: ArcRwLockWriteGuard<'_, TcpStream> = self.write().await;
        stream
            .flush()
            .await
            .map_err(|e| ResponseError::FlushError(e.to_string()))?;
        Ok(())
    }

    /// Flushes the stream.
    ///
    /// # Panics
    ///
    /// Panics if the flush operation fails.
    pub async fn flush(&self) {
        self.try_flush().await.unwrap();
    }

    /// Attempts to get the peer address.
    ///
    /// # Returns
    ///
    /// - `OptionSocketAddr` - The peer address if available.
    pub async fn try_get_peer_addr(&self) -> OptionSocketAddr {
        let stream: ArcRwLockReadGuard<'_, TcpStream> = self.read().await;
        stream.peer_addr().ok()
    }

    /// Gets the peer address.
    ///
    /// # Returns
    ///
    /// - `SocketAddr` - The peer address.
    ///
    /// # Panics
    ///
    /// Panics if the peer address is not available.
    pub async fn get_peer_addr(&self) -> SocketAddr {
        self.try_get_peer_addr().await.unwrap()
    }

    /// Attempts to shut down the stream.
    ///
    /// # Returns
    ///
    /// - `ResponseResult` - Ok(()) on success, or an error on failure.
    pub async fn try_shutdown(&self) -> ResponseResult {
        let mut stream: ArcRwLockWriteGuard<'_, TcpStream> = self.write().await;
        stream
            .shutdown()
            .await
            .map_err(|e| ResponseError::WriteError(e.to_string()))?;
        Ok(())
    }

    /// Shuts down the stream.
    ///
    /// # Panics
    ///
    /// Panics if the shutdown operation fails.
    pub async fn shutdown(&self) {
        self.try_shutdown().await.unwrap();
    }
}

/// Implementation of `From<TcpStream>` for `ArcRwLockStream`.
impl From<TcpStream> for ArcRwLockStream {
    /// Converts a `TcpStream` into an `ArcRwLockStream`.
    ///
    /// # Arguments
    ///
    /// - `TcpStream` - The TCP stream to convert.
    ///
    /// # Returns
    ///
    /// - `Self` - A new ArcRwLockStream instance.
    fn from(stream: TcpStream) -> Self {
        Self::from_stream(stream)
    }
}