pub struct TcpSocket { /* private fields */ }
Expand description
A TCP socket that has not yet been converted to a TcpStream
or
TcpListener
.
TcpSocket
wraps an operating system socket and enables the caller to
configure the socket before establishing a TCP connection or accepting
inbound connections. The caller is able to set socket option and explicitly
bind the socket with a socket address.
The underlying socket is closed when the TcpSocket
value is dropped.
TcpSocket
should only be used directly if the default configuration used
by TcpStream::connect
and TcpListener::bind
does not meet the required
use case.
Calling TcpStream::connect("127.0.0.1:8080")
is equivalent to:
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()?;
let stream = socket.connect(addr).await?;
Ok(())
}
Calling TcpListener::bind("127.0.0.1:8080")
is equivalent to:
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)?;
let listener = socket.listen(1024)?;
Ok(())
}
Setting socket options not explicitly provided by TcpSocket
may be done by
accessing the RawFd
/RawSocket
using AsRawFd
/AsRawSocket
and
setting the option with a crate like socket2
.
Implementations§
Source§impl TcpSocket
impl TcpSocket
Sourcepub fn new_v4() -> Result<TcpSocket>
pub fn new_v4() -> Result<TcpSocket>
Creates a new socket configured for IPv4.
Calls socket(2)
with AF_INET
and SOCK_STREAM
.
§Returns
On success, the newly created TcpSocket
is returned. If an error is
encountered, it is returned instead.
§Examples
Create a new IPv4 socket and start listening.
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()?;
socket.bind(addr)?;
let listener = socket.listen(128)?;
Ok(())
}
Sourcepub fn new_v6() -> Result<TcpSocket>
pub fn new_v6() -> Result<TcpSocket>
Creates a new socket configured for IPv6.
Calls socket(2)
with AF_INET6
and SOCK_STREAM
.
§Returns
On success, the newly created TcpSocket
is returned. If an error is
encountered, it is returned instead.
§Examples
Create a new IPv6 socket and start listening.
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)?;
Ok(())
}
Sourcepub fn set_keepalive(&self, keepalive: bool) -> Result<()>
pub fn set_keepalive(&self, keepalive: bool) -> Result<()>
Sets value for the SO_KEEPALIVE
option on this socket.
Sourcepub fn keepalive(&self) -> Result<bool>
pub fn keepalive(&self) -> Result<bool>
Gets the value of the SO_KEEPALIVE
option on this socket.
Sourcepub fn set_reuseaddr(&self, reuseaddr: bool) -> Result<()>
pub fn set_reuseaddr(&self, reuseaddr: bool) -> Result<()>
Allows the socket to bind to an in-use address.
Behavior is platform specific. Refer to the target platform’s documentation for more details.
§Examples
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()?;
socket.set_reuseaddr(true)?;
socket.bind(addr)?;
let listener = socket.listen(1024)?;
Ok(())
}
Sourcepub fn reuseaddr(&self) -> Result<bool>
pub fn reuseaddr(&self) -> Result<bool>
Retrieves the value set for SO_REUSEADDR
on this socket.
§Examples
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()?;
socket.set_reuseaddr(true)?;
assert!(socket.reuseaddr().unwrap());
socket.bind(addr)?;
let listener = socket.listen(1024)?;
Ok(())
}
Sourcepub fn set_reuseport(&self, reuseport: bool) -> Result<()>
pub fn set_reuseport(&self, reuseport: bool) -> Result<()>
Allows the socket to bind to an in-use port. Only available for unix systems (excluding Solaris & Illumos).
Behavior is platform specific. Refer to the target platform’s documentation for more details.
§Examples
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()?;
socket.set_reuseport(true)?;
socket.bind(addr)?;
let listener = socket.listen(1024)?;
Ok(())
}
Sourcepub fn reuseport(&self) -> Result<bool>
pub fn reuseport(&self) -> Result<bool>
Allows the socket to bind to an in-use port. Only available for unix systems (excluding Solaris & Illumos).
Behavior is platform specific. Refer to the target platform’s documentation for more details.
§Examples
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()?;
socket.set_reuseport(true)?;
assert!(socket.reuseport().unwrap());
socket.bind(addr)?;
let listener = socket.listen(1024)?;
Ok(())
}
Sourcepub fn set_send_buffer_size(&self, size: u32) -> Result<()>
pub fn set_send_buffer_size(&self, size: u32) -> Result<()>
Sets the size of the TCP send buffer on this socket.
On most operating systems, this sets the SO_SNDBUF
socket option.
Sourcepub fn send_buffer_size(&self) -> Result<u32>
pub fn send_buffer_size(&self) -> Result<u32>
Returns the size of the TCP send buffer for this socket.
On most operating systems, this is the value of the SO_SNDBUF
socket
option.
Note that if set_send_buffer_size
has been called on this socket
previously, the value returned by this function may not be the same as
the argument provided to set_send_buffer_size
. This is for the
following reasons:
- Most operating systems have minimum and maximum allowed sizes for the send buffer, and will clamp the provided value if it is below the minimum or above the maximum. The minimum and maximum buffer sizes are OS-dependent.
- Linux will double the buffer size to account for internal bookkeeping
data, and returns the doubled value from
getsockopt(2)
. As perman 7 socket
:Sets or gets the maximum socket send buffer in bytes. The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using
setsockopt(2)
, and this doubled value is returned bygetsockopt(2)
.
Sourcepub fn set_recv_buffer_size(&self, size: u32) -> Result<()>
pub fn set_recv_buffer_size(&self, size: u32) -> Result<()>
Sets the size of the TCP receive buffer on this socket.
On most operating systems, this sets the SO_RCVBUF
socket option.
Sourcepub fn recv_buffer_size(&self) -> Result<u32>
pub fn recv_buffer_size(&self) -> Result<u32>
Returns the size of the TCP receive buffer for this socket.
On most operating systems, this is the value of the SO_RCVBUF
socket
option.
Note that if set_recv_buffer_size
has been called on this socket
previously, the value returned by this function may not be the same as
the argument provided to set_send_buffer_size
. This is for the
following reasons:
- Most operating systems have minimum and maximum allowed sizes for the receive buffer, and will clamp the provided value if it is below the minimum or above the maximum. The minimum and maximum buffer sizes are OS-dependent.
- Linux will double the buffer size to account for internal bookkeeping
data, and returns the doubled value from
getsockopt(2)
. As perman 7 socket
:Sets or gets the maximum socket send buffer in bytes. The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using
setsockopt(2)
, and this doubled value is returned bygetsockopt(2)
.
Sourcepub fn set_linger(&self, dur: Option<Duration>) -> Result<()>
pub fn set_linger(&self, dur: Option<Duration>) -> Result<()>
Sets the linger duration of this socket by setting the SO_LINGER
option.
This option controls the action taken when a stream has unsent messages and the stream is
closed. If SO_LINGER
is set, the system shall block the process until it can transmit the
data or until the time expires.
If SO_LINGER
is not specified, and the socket is closed, the system handles the call in a
way that allows the process to continue as quickly as possible.
Sourcepub fn linger(&self) -> Result<Option<Duration>>
pub fn linger(&self) -> Result<Option<Duration>>
Reads the linger duration for this socket by getting the SO_LINGER
option.
For more information about this option, see set_linger
.
Sourcepub fn set_nodelay(&self, nodelay: bool) -> Result<()>
pub fn set_nodelay(&self, nodelay: bool) -> Result<()>
Sets the value of the TCP_NODELAY
option on this socket.
If set, this option disables the Nagle algorithm. This means that segments are always sent as soon as possible, even if there is only a small amount of data. When not set, data is buffered until there is a sufficient amount to send out, thereby avoiding the frequent sending of small packets.
§Examples
use tokio::net::TcpSocket;
let socket = TcpSocket::new_v4()?;
socket.set_nodelay(true)?;
Sourcepub fn nodelay(&self) -> Result<bool>
pub fn nodelay(&self) -> Result<bool>
Gets the value of the TCP_NODELAY
option on this socket.
For more information about this option, see set_nodelay
.
§Examples
use tokio::net::TcpSocket;
let socket = TcpSocket::new_v4()?;
println!("{:?}", socket.nodelay()?);
Sourcepub fn tos(&self) -> Result<u32>
pub fn tos(&self) -> Result<u32>
Gets the value of the IP_TOS
option for this socket.
For more information about this option, see set_tos
.
NOTE: On Windows, IP_TOS
is only supported on Windows 8+ or
Windows Server 2012+.
Sourcepub fn set_tos(&self, tos: u32) -> Result<()>
pub fn set_tos(&self, tos: u32) -> Result<()>
Sets the value for the IP_TOS
option on this socket.
This value sets the type-of-service field that is used in every packet sent from this socket.
NOTE: On Windows, IP_TOS
is only supported on Windows 8+ or
Windows Server 2012+.
Sourcepub fn device(&self) -> Result<Option<Vec<u8>>>
pub fn device(&self) -> Result<Option<Vec<u8>>>
Gets the value for the SO_BINDTODEVICE
option on this socket
This value gets the socket binded device’s interface name.
Sourcepub fn bind_device(&self, interface: Option<&[u8]>) -> Result<()>
pub fn bind_device(&self, interface: Option<&[u8]>) -> Result<()>
Sets the value for the SO_BINDTODEVICE
option on this socket
If a socket is bound to an interface, only packets received from that
particular interface are processed by the socket. Note that this only
works for some socket types, particularly AF_INET
sockets.
If interface
is None
or an empty string it removes the binding.
Sourcepub fn local_addr(&self) -> Result<SocketAddr>
pub fn local_addr(&self) -> Result<SocketAddr>
Gets the local address of this socket.
Will fail on windows if called before bind
.
§Examples
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()?;
socket.bind(addr)?;
assert_eq!(socket.local_addr().unwrap().to_string(), "127.0.0.1:8080");
let listener = socket.listen(1024)?;
Ok(())
}
Sourcepub fn take_error(&self) -> Result<Option<Error>>
pub fn take_error(&self) -> Result<Option<Error>>
Returns the value of the SO_ERROR
option.
Sourcepub fn bind(&self, addr: SocketAddr) -> Result<()>
pub fn bind(&self, addr: SocketAddr) -> Result<()>
Binds the socket to the given address.
This calls the bind(2)
operating-system function. Behavior is
platform specific. Refer to the target platform’s documentation for more
details.
§Examples
Bind a socket before listening.
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()?;
socket.bind(addr)?;
let listener = socket.listen(1024)?;
Ok(())
}
Sourcepub async fn connect(self, addr: SocketAddr) -> Result<TcpStream>
pub async fn connect(self, addr: SocketAddr) -> Result<TcpStream>
Establishes a TCP connection with a peer at the specified socket address.
The TcpSocket
is consumed. Once the connection is established, a
connected TcpStream
is returned. If the connection fails, the
encountered error is returned.
This calls the connect(2)
operating-system function. Behavior is
platform specific. Refer to the target platform’s documentation for more
details.
§Examples
Connecting to a peer.
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()?;
let stream = socket.connect(addr).await?;
Ok(())
}
Sourcepub fn listen(self, backlog: u32) -> Result<TcpListener>
pub fn listen(self, backlog: u32) -> Result<TcpListener>
Converts the socket into a TcpListener
.
backlog
defines the maximum number of pending connections are queued
by the operating system at any given time. Connection are removed from
the queue with TcpListener::accept
. When the queue is full, the
operating-system will start rejecting connections.
This calls the listen(2)
operating-system function, marking the socket
as a passive socket. Behavior is platform specific. Refer to the target
platform’s documentation for more details.
§Examples
Create a TcpListener
.
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()?;
socket.bind(addr)?;
let listener = socket.listen(1024)?;
Ok(())
}
Sourcepub fn from_std_stream(std_stream: TcpStream) -> TcpSocket
pub fn from_std_stream(std_stream: TcpStream) -> TcpSocket
Converts a std::net::TcpStream
into a TcpSocket
. The provided
socket must not have been connected prior to calling this function. This
function is typically used together with crates such as socket2
to
configure socket options that are not available on TcpSocket
.
§Notes
The caller is responsible for ensuring that the socket is in
non-blocking mode. Otherwise all I/O operations on the socket
will block the thread, which will cause unexpected behavior.
Non-blocking mode can be set using set_nonblocking
.
§Examples
use tokio::net::TcpSocket;
use socket2::{Domain, Socket, Type};
#[tokio::main]
async fn main() -> std::io::Result<()> {
let socket2_socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;
socket2_socket.set_nonblocking(true)?;
let socket = TcpSocket::from_std_stream(socket2_socket.into());
Ok(())
}