WPILibC++ 2024.3.2
wpi::uv::Tcp Class Referencefinal

TCP handle. More...

#include <wpinet/uv/Tcp.h>

Inheritance diagram for wpi::uv::Tcp:
wpi::uv::NetworkStreamImpl< Tcp, uv_tcp_t > wpi::uv::NetworkStream wpi::uv::Stream wpi::uv::Handle

Public Types

using Time = std::chrono::duration< uint64_t, std::milli >
 
- Public Types inherited from wpi::uv::Handle
using Type = uv_handle_type
 

Public Member Functions

 Tcp (const private_init &)
 
 ~Tcp () noexcept override=default
 
void Reuse (std::function< void()> callback, unsigned int flags=AF_UNSPEC)
 Reuse this handle. More...
 
std::shared_ptr< TcpAccept ()
 Accept incoming connection. More...
 
bool Accept (const std::shared_ptr< Tcp > &client)
 Accept incoming connection. More...
 
void Open (uv_os_sock_t sock)
 Open an existing file descriptor or SOCKET as a TCP handle. More...
 
bool SetNoDelay (bool enable)
 Enable no delay operation (turns off Nagle's algorithm). More...
 
bool SetKeepAlive (bool enable, Time time=Time{0})
 Enable/Disable TCP keep-alive. More...
 
bool SetSimultaneousAccepts (bool enable)
 Enable/Disable simultaneous asynchronous accept requests. More...
 
void Bind (const sockaddr &addr, unsigned int flags=0)
 Bind the handle to an IPv4 or IPv6 address and port. More...
 
void Bind (const sockaddr_in &addr, unsigned int flags=0)
 
void Bind (const sockaddr_in6 &addr, unsigned int flags=0)
 
void Bind (std::string_view ip, unsigned int port, unsigned int flags=0)
 Bind the handle to an IPv4 address and port. More...
 
void Bind6 (std::string_view ip, unsigned int port, unsigned int flags=0)
 Bind the handle to an IPv6 address and port. More...
 
sockaddr_storage GetSock ()
 Get the current address to which the handle is bound. More...
 
sockaddr_storage GetPeer ()
 Get the address of the peer connected to the handle. More...
 
void Connect (const sockaddr &addr, const std::shared_ptr< TcpConnectReq > &req)
 Establish an IPv4 or IPv6 TCP connection. More...
 
void Connect (const sockaddr_in &addr, const std::shared_ptr< TcpConnectReq > &req)
 
void Connect (const sockaddr_in6 &addr, const std::shared_ptr< TcpConnectReq > &req)
 
void Connect (const sockaddr &addr, std::function< void()> callback)
 Establish an IPv4 or IPv6 TCP connection. More...
 
void Connect (const sockaddr_in &addr, std::function< void()> callback)
 
void Connect (const sockaddr_in6 &addr, std::function< void()> callback)
 
void Connect (std::string_view ip, unsigned int port, const std::shared_ptr< TcpConnectReq > &req)
 Establish an IPv4 TCP connection. More...
 
void Connect (std::string_view ip, unsigned int port, std::function< void()> callback)
 Establish an IPv4 TCP connection. More...
 
void Connect6 (std::string_view ip, unsigned int port, const std::shared_ptr< TcpConnectReq > &req)
 Establish an IPv6 TCP connection. More...
 
void Connect6 (std::string_view ip, unsigned int port, std::function< void()> callback)
 Establish an IPv6 TCP connection. More...
 
void CloseReset ()
 Resets a TCP connection by sending a RST packet. More...
 
- Public Member Functions inherited from wpi::uv::NetworkStreamImpl< Tcp, uv_tcp_t >
std::shared_ptr< Tcpshared_from_this ()
 
std::shared_ptr< const Tcpshared_from_this () const
 
uv_tcp_tGetRaw () const noexcept
 Get the underlying handle data structure. More...
 
- Public Member Functions inherited from wpi::uv::NetworkStream
std::shared_ptr< NetworkStreamshared_from_this ()
 
std::shared_ptr< const NetworkStreamshared_from_this () const
 
void Listen (int backlog=kDefaultBacklog)
 Start listening for incoming connections. More...
 
void Listen (std::function< void()> callback, int backlog=kDefaultBacklog)
 Start listening for incoming connections. More...
 
std::shared_ptr< NetworkStreamAccept ()
 Accept incoming connection. More...
 
bool Accept (const std::shared_ptr< NetworkStream > &client)
 Accept incoming connection. More...
 
- Public Member Functions inherited from wpi::uv::Stream
std::shared_ptr< Streamshared_from_this ()
 
std::shared_ptr< const Streamshared_from_this () const
 
void Shutdown (const std::shared_ptr< ShutdownReq > &req)
 Shutdown the outgoing (write) side of a duplex stream. More...
 
void Shutdown (std::function< void()> callback=nullptr)
 Shutdown the outgoing (write) side of a duplex stream. More...
 
void StartRead ()
 Start reading data from an incoming stream. More...
 
void StopRead ()
 Stop reading data from the stream. More...
 
void Write (std::span< const Buffer > bufs, const std::shared_ptr< WriteReq > &req)
 Write data to the stream. More...
 
void Write (std::initializer_list< Buffer > bufs, const std::shared_ptr< WriteReq > &req)
 Write data to the stream. More...
 
void Write (std::span< const Buffer > bufs, std::function< void(std::span< Buffer >, Error)> callback)
 Write data to the stream. More...
 
void Write (std::initializer_list< Buffer > bufs, std::function< void(std::span< Buffer >, Error)> callback)
 Write data to the stream. More...
 
int TryWrite (std::span< const Buffer > bufs)
 Queue a write request if it can be completed immediately. More...
 
int TryWrite (std::initializer_list< Buffer > bufs)
 Queue a write request if it can be completed immediately. More...
 
int TryWrite2 (std::span< const Buffer > bufs, Stream &send)
 Same as TryWrite() and extended write function for sending handles over a pipe. More...
 
int TryWrite2 (std::initializer_list< Buffer > bufs, Stream &send)
 Same as TryWrite() and extended write function for sending handles over a pipe. More...
 
bool IsReadable () const noexcept
 Check if the stream is readable. More...
 
bool IsWritable () const noexcept
 Checks if the stream is writable. More...
 
bool SetBlocking (bool enable) noexcept
 Enable or disable blocking mode for a stream. More...
 
size_t GetWriteQueueSize () const noexcept
 Gets the amount of queued bytes waiting to be sent. More...
 
uv_stream_tGetRawStream () const noexcept
 Get the underlying stream data structure. More...
 
- Public Member Functions inherited from wpi::uv::Handle
 Handle (const Handle &)=delete
 
 Handle (Handle &&)=delete
 
Handleoperator= (const Handle &)=delete
 
Handleoperator= (Handle &&)=delete
 
virtual ~Handle () noexcept
 
Type GetType () const noexcept
 Get the type of the handle. More...
 
std::string_view GetTypeName () const noexcept
 Get the name of the type of the handle. More...
 
std::shared_ptr< LoopGetLoop () const noexcept
 Get the loop where this handle runs. More...
 
LoopGetLoopRef () const noexcept
 Get the loop where this handle runs. More...
 
bool IsActive () const noexcept
 Check if the handle is active. More...
 
bool IsClosing () const noexcept
 Check if a handle is closing or closed. More...
 
void Close () noexcept
 Request handle to be closed. More...
 
void SetLoopClosing (bool loopClosing) noexcept
 Set if the loop is closing. More...
 
bool IsLoopClosing () const noexcept
 Get the loop closing status. More...
 
void Reference () noexcept
 Reference the given handle. More...
 
void Unreference () noexcept
 Unreference the given handle. More...
 
bool HasReference () const noexcept
 Check if the given handle is referenced. More...
 
size_t RawSize () const noexcept
 Return the size of the underlying handle type. More...
 
uv_handle_tGetRawHandle () const noexcept
 Get the underlying handle data structure. More...
 
void SetBufferAllocator (std::function< Buffer(size_t)> alloc, std::function< void(Buffer &)> dealloc)
 Set the functions used for allocating and releasing buffers. More...
 
void FreeBuf (Buffer &buf) const noexcept
 Free a buffer. More...
 
template<typename T = void>
std::shared_ptr< T > GetData () const
 Gets user-defined data. More...
 
void SetData (std::shared_ptr< void > data)
 Sets user-defined data. More...
 
void SetLogger (Logger *logger)
 Sets logger. More...
 
LoggerGetLogger () const
 Gets logger. More...
 
void ReportError (int err) const
 Report an error. More...
 

Static Public Member Functions

static std::shared_ptr< TcpCreate (Loop &loop, unsigned int flags=AF_UNSPEC)
 Create a TCP handle. More...
 
static std::shared_ptr< TcpCreate (const std::shared_ptr< Loop > &loop, unsigned int flags=AF_UNSPEC)
 Create a TCP handle. More...
 

Additional Inherited Members

- Public Attributes inherited from wpi::uv::NetworkStream
sig::Signal connection
 Signal generated when an incoming connection is received. More...
 
- Public Attributes inherited from wpi::uv::Stream
sig::Signal< Buffer &, size_t > data
 Signal generated when data was read on a stream. More...
 
sig::Signal end
 Signal generated when no more read data is available. More...
 
- Public Attributes inherited from wpi::uv::Handle
sig::Signal< Errorerror
 Error signal. More...
 
sig::Signal closed
 Closed signal. More...
 
- Static Public Attributes inherited from wpi::uv::NetworkStream
static constexpr int kDefaultBacklog = 128
 
- Protected Member Functions inherited from wpi::uv::NetworkStreamImpl< Tcp, uv_tcp_t >
 NetworkStreamImpl ()
 
- Protected Member Functions inherited from wpi::uv::NetworkStream
 NetworkStream (uv_stream_t *uv_stream)
 
virtual NetworkStreamDoAccept ()=0
 
- Protected Member Functions inherited from wpi::uv::Stream
 Stream (uv_stream_t *uv_stream)
 
- Protected Member Functions inherited from wpi::uv::Handle
 Handle (uv_handle_t *uv_handle)
 
void Keep () noexcept
 
void Release () noexcept
 
void ForceClosed () noexcept
 
template<typename F , typename... Args>
bool Invoke (F &&f, Args &&... args) const
 
- Static Protected Member Functions inherited from wpi::uv::Handle
static void AllocBuf (uv_handle_t *handle, size_t size, uv_buf_t *buf)
 
static void DefaultFreeBuf (Buffer &buf)
 

Detailed Description

TCP handle.

TCP handles are used to represent both TCP streams and servers.

Member Typedef Documentation

◆ Time

using wpi::uv::Tcp::Time = std::chrono::duration<uint64_t, std::milli>

Constructor & Destructor Documentation

◆ Tcp()

wpi::uv::Tcp::Tcp ( const private_init &  )
inlineexplicit

◆ ~Tcp()

wpi::uv::Tcp::~Tcp ( )
overridedefaultnoexcept

Member Function Documentation

◆ Accept() [1/2]

std::shared_ptr< Tcp > wpi::uv::Tcp::Accept ( )

Accept incoming connection.

This call is used in conjunction with Listen() to accept incoming connections. Call this function after receiving a ListenEvent event to accept the connection. An error signal will be emitted in case of errors.

When the connection signal is emitted it is guaranteed that this function will complete successfully the first time. If you attempt to use it more than once, it may fail. It is suggested to only call this function once per connection signal.

Returns
The stream handle for the accepted connection, or nullptr on error.

◆ Accept() [2/2]

bool wpi::uv::Tcp::Accept ( const std::shared_ptr< Tcp > &  client)
inline

Accept incoming connection.

This call is used in conjunction with Listen() to accept incoming connections. Call this function after receiving a connection signal to accept the connection. An error signal will be emitted in case of errors.

When the connection signal is emitted it is guaranteed that this function will complete successfully the first time. If you attempt to use it more than once, it may fail. It is suggested to only call this function once per connection signal.

Parameters
clientClient stream object.
Returns
False on error.

◆ Bind() [1/4]

void wpi::uv::Tcp::Bind ( const sockaddr &  addr,
unsigned int  flags = 0 
)
inline

Bind the handle to an IPv4 or IPv6 address and port.

A successful call to this function does not guarantee that the call to Listen() or Connect() will work properly. An error signal can be emitted because of either this function or the ones mentioned above.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.
flagsOptional additional flags.

◆ Bind() [2/4]

void wpi::uv::Tcp::Bind ( const sockaddr_in &  addr,
unsigned int  flags = 0 
)
inline

◆ Bind() [3/4]

void wpi::uv::Tcp::Bind ( const sockaddr_in6 &  addr,
unsigned int  flags = 0 
)
inline

◆ Bind() [4/4]

void wpi::uv::Tcp::Bind ( std::string_view  ip,
unsigned int  port,
unsigned int  flags = 0 
)

Bind the handle to an IPv4 address and port.

A successful call to this function does not guarantee that the call to Listen() or Connect() will work properly. An error signal can be emitted because of either this function or the ones mentioned above.

Available flags are:

Parameters
ipThe address to which to bind.
portThe port to which to bind.
flagsOptional additional flags.

◆ Bind6()

void wpi::uv::Tcp::Bind6 ( std::string_view  ip,
unsigned int  port,
unsigned int  flags = 0 
)

Bind the handle to an IPv6 address and port.

A successful call to this function does not guarantee that the call to Listen() or Connect() will work properly. An error signal can be emitted because of either this function or the ones mentioned above.

Available flags are:

Parameters
ipThe address to which to bind.
portThe port to which to bind.
flagsOptional additional flags.

◆ CloseReset()

void wpi::uv::Tcp::CloseReset ( )

Resets a TCP connection by sending a RST packet.

This is accomplished by setting the SO_LINGER socket option with a linger interval of zero and then calling Close(). Due to some platform inconsistencies, mixing of Shutdown() and CloseReset() calls is not allowed.

◆ Connect() [1/8]

void wpi::uv::Tcp::Connect ( const sockaddr &  addr,
const std::shared_ptr< TcpConnectReq > &  req 
)

Establish an IPv4 or IPv6 TCP connection.

On Windows if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. This is done to match the behavior of Linux systems.

The connected signal is emitted on the request when the connection has been established. The error signal is emitted on the request in case of errors during the connection.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.
reqconnection request

◆ Connect() [2/8]

void wpi::uv::Tcp::Connect ( const sockaddr &  addr,
std::function< void()>  callback 
)

Establish an IPv4 or IPv6 TCP connection.

On Windows if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. This is done to match the behavior of Linux systems.

The callback is called when the connection has been established. Errors are reported to the stream error handler.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.
callbackCallback function to call when connection established

◆ Connect() [3/8]

void wpi::uv::Tcp::Connect ( const sockaddr_in &  addr,
const std::shared_ptr< TcpConnectReq > &  req 
)
inline

◆ Connect() [4/8]

void wpi::uv::Tcp::Connect ( const sockaddr_in &  addr,
std::function< void()>  callback 
)
inline

◆ Connect() [5/8]

void wpi::uv::Tcp::Connect ( const sockaddr_in6 &  addr,
const std::shared_ptr< TcpConnectReq > &  req 
)
inline

◆ Connect() [6/8]

void wpi::uv::Tcp::Connect ( const sockaddr_in6 &  addr,
std::function< void()>  callback 
)
inline

◆ Connect() [7/8]

void wpi::uv::Tcp::Connect ( std::string_view  ip,
unsigned int  port,
const std::shared_ptr< TcpConnectReq > &  req 
)

Establish an IPv4 TCP connection.

On Windows if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. This is done to match the behavior of Linux systems.

The connected signal is emitted on the request when the connection has been established. The error signal is emitted on the request in case of errors during the connection.

Parameters
ipThe address to which to connect to.
portThe port to which to connect to.
reqconnection request

◆ Connect() [8/8]

void wpi::uv::Tcp::Connect ( std::string_view  ip,
unsigned int  port,
std::function< void()>  callback 
)

Establish an IPv4 TCP connection.

On Windows if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. This is done to match the behavior of Linux systems.

The callback is called when the connection has been established. Errors are reported to the stream error handler.

Parameters
ipThe address to which to connect to.
portThe port to which to connect to.
callbackCallback function to call when connection established

◆ Connect6() [1/2]

void wpi::uv::Tcp::Connect6 ( std::string_view  ip,
unsigned int  port,
const std::shared_ptr< TcpConnectReq > &  req 
)

Establish an IPv6 TCP connection.

On Windows if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. This is done to match the behavior of Linux systems.

The connected signal is emitted on the request when the connection has been established. The error signal is emitted on the request in case of errors during the connection.

Parameters
ipThe address to which to connect to.
portThe port to which to connect to.
reqconnection request

◆ Connect6() [2/2]

void wpi::uv::Tcp::Connect6 ( std::string_view  ip,
unsigned int  port,
std::function< void()>  callback 
)

Establish an IPv6 TCP connection.

On Windows if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. This is done to match the behavior of Linux systems.

The callback is called when the connection has been established. Errors are reported to the stream error handler.

Parameters
ipThe address to which to connect to.
portThe port to which to connect to.
callbackCallback function to call when connection established

◆ Create() [1/2]

static std::shared_ptr< Tcp > wpi::uv::Tcp::Create ( const std::shared_ptr< Loop > &  loop,
unsigned int  flags = AF_UNSPEC 
)
inlinestatic

Create a TCP handle.

Parameters
loopLoop object where this handle runs.
flagsFlags

◆ Create() [2/2]

static std::shared_ptr< Tcp > wpi::uv::Tcp::Create ( Loop loop,
unsigned int  flags = AF_UNSPEC 
)
static

Create a TCP handle.

Parameters
loopLoop object where this handle runs.
flagsFlags

◆ GetPeer()

sockaddr_storage wpi::uv::Tcp::GetPeer ( )

Get the address of the peer connected to the handle.

Returns
The address (will be zeroed if an error occurred).

◆ GetSock()

sockaddr_storage wpi::uv::Tcp::GetSock ( )

Get the current address to which the handle is bound.

Returns
The address (will be zeroed if an error occurred).

◆ Open()

void wpi::uv::Tcp::Open ( uv_os_sock_t  sock)
inline

Open an existing file descriptor or SOCKET as a TCP handle.

Note
The passed file descriptor or SOCKET is not checked for its type, but it's required that it represents a valid stream socket.
Parameters
sockA valid socket handle (either a file descriptor or a SOCKET).

◆ Reuse()

void wpi::uv::Tcp::Reuse ( std::function< void()>  callback,
unsigned int  flags = AF_UNSPEC 
)

Reuse this handle.

This closes the handle, and after the close completes, reinitializes it (identically to Create) and calls the provided callback. Unlike Close(), it does NOT emit the closed signal, however, IsClosing() will return true until the callback is called. This does nothing if IsClosing() is true (e.g. if Close() was called).

Parameters
flagsFlags
callbackCallback

◆ SetKeepAlive()

bool wpi::uv::Tcp::SetKeepAlive ( bool  enable,
Time  time = Time{0} 
)
inline

Enable/Disable TCP keep-alive.

Parameters
enableTrue to enable it, false otherwise.
timeInitial delay in seconds (use std::chrono::duration<unsigned int>).
Returns
True in case of success, false otherwise.

◆ SetNoDelay()

bool wpi::uv::Tcp::SetNoDelay ( bool  enable)
inline

Enable no delay operation (turns off Nagle's algorithm).

Parameters
enableTrue to enable it, false otherwise.
Returns
True in case of success, false otherwise.

◆ SetSimultaneousAccepts()

bool wpi::uv::Tcp::SetSimultaneousAccepts ( bool  enable)
inline

Enable/Disable simultaneous asynchronous accept requests.

Enable/Disable simultaneous asynchronous accept requests that are queued by the operating system when listening for new TCP connections. This setting is used to tune a TCP server for the desired performance. Having simultaneous accepts can significantly improve the rate of accepting connections (which is why it is enabled by default) but may lead to uneven load distribution in multi-process setups.

Parameters
enableTrue to enable it, false otherwise.
Returns
True in case of success, false otherwise.

The documentation for this class was generated from the following file: