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

Pipe handle. More...

#include <wpinet/uv/Pipe.h>

Inheritance diagram for wpi::uv::Pipe:
wpi::uv::NetworkStreamImpl< Pipe, uv_pipe_t > wpi::uv::NetworkStream wpi::uv::Stream wpi::uv::Handle

Public Member Functions

 Pipe (const private_init &)
 
 ~Pipe () noexcept override=default
 
void Reuse (std::function< void()> callback, bool ipc=false)
 Reuse this handle. More...
 
std::shared_ptr< PipeAccept ()
 Accept incoming connection. More...
 
bool Accept (const std::shared_ptr< Pipe > &client)
 Accept incoming connection. More...
 
void Open (uv_file file)
 Open an existing file descriptor or HANDLE as a pipe. More...
 
void Bind (std::string_view name)
 Bind the pipe to a file path (Unix) or a name (Windows). More...
 
void Connect (std::string_view name, const std::shared_ptr< PipeConnectReq > &req)
 Connect to the Unix domain socket or the named pipe. More...
 
void Connect (std::string_view name, std::function< void()> callback)
 Connect to the Unix domain socket or the named pipe. More...
 
std::string GetSock ()
 Get the name of the Unix domain socket or the named pipe. More...
 
std::string GetPeer ()
 Get the name of the Unix domain socket or the named pipe to which the handle is connected. More...
 
void SetPendingInstances (int count)
 Set the number of pending pipe instance handles when the pipe server is waiting for connections. More...
 
void Chmod (int flags)
 Alters pipe permissions, allowing it to be accessed from processes run by different users. More...
 
- Public Member Functions inherited from wpi::uv::NetworkStreamImpl< Pipe, uv_pipe_t >
std::shared_ptr< Pipeshared_from_this ()
 
std::shared_ptr< const Pipeshared_from_this () const
 
uv_pipe_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< PipeCreate (Loop &loop, bool ipc=false)
 Create a pipe handle. More...
 
static std::shared_ptr< PipeCreate (const std::shared_ptr< Loop > &loop, bool ipc=false)
 Create a pipe handle. More...
 

Additional Inherited Members

- Public Types inherited from wpi::uv::Handle
using Type = uv_handle_type
 
- 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< Pipe, uv_pipe_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

Pipe handle.

Pipe handles provide an abstraction over local domain sockets on Unix and named pipes on Windows.

Constructor & Destructor Documentation

◆ Pipe()

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

◆ ~Pipe()

wpi::uv::Pipe::~Pipe ( )
overridedefaultnoexcept

Member Function Documentation

◆ Accept() [1/2]

std::shared_ptr< Pipe > wpi::uv::Pipe::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::Pipe::Accept ( const std::shared_ptr< Pipe > &  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()

void wpi::uv::Pipe::Bind ( std::string_view  name)

Bind the pipe to a file path (Unix) or a name (Windows).

Note
Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes, typically between 92 and 108 bytes.
Parameters
nameFile path (Unix) or name (Windows).

◆ Chmod()

void wpi::uv::Pipe::Chmod ( int  flags)
inline

Alters pipe permissions, allowing it to be accessed from processes run by different users.

Makes the pipe writable or readable by all users. Mode can be UV_WRITABLE, UV_READABLE, or both. This function is blocking.

Parameters
flagschmod flags

◆ Connect() [1/2]

void wpi::uv::Pipe::Connect ( std::string_view  name,
const std::shared_ptr< PipeConnectReq > &  req 
)

Connect to the Unix domain socket or the named pipe.

Note
Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes, typically between 92 and 108 bytes.

HandleConnected() is called on the request when the connection has been established. HandleError() is called on the request in case of errors during the connection.

Parameters
nameFile path (Unix) or name (Windows).
reqconnection request

◆ Connect() [2/2]

void wpi::uv::Pipe::Connect ( std::string_view  name,
std::function< void()>  callback 
)

Connect to the Unix domain socket or the named pipe.

Note
Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes, typically between 92 and 108 bytes.

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

Parameters
nameFile path (Unix) or name (Windows).
callbackCallback function to call when connection established

◆ Create() [1/2]

static std::shared_ptr< Pipe > wpi::uv::Pipe::Create ( const std::shared_ptr< Loop > &  loop,
bool  ipc = false 
)
inlinestatic

Create a pipe handle.

Parameters
loopLoop object where this handle runs.
ipcIndicates if this pipe will be used for handle passing between processes.

◆ Create() [2/2]

static std::shared_ptr< Pipe > wpi::uv::Pipe::Create ( Loop loop,
bool  ipc = false 
)
static

Create a pipe handle.

Parameters
loopLoop object where this handle runs.
ipcIndicates if this pipe will be used for handle passing between processes.

◆ GetPeer()

std::string wpi::uv::Pipe::GetPeer ( )

Get the name of the Unix domain socket or the named pipe to which the handle is connected.

Returns
The name (will be empty if an error occurred).

◆ GetSock()

std::string wpi::uv::Pipe::GetSock ( )

Get the name of the Unix domain socket or the named pipe.

Returns
The name (will be empty if an error occurred).

◆ Open()

void wpi::uv::Pipe::Open ( uv_file  file)
inline

Open an existing file descriptor or HANDLE as a pipe.

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

◆ Reuse()

void wpi::uv::Pipe::Reuse ( std::function< void()>  callback,
bool  ipc = false 
)

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
ipcIPC
callbackCallback

◆ SetPendingInstances()

void wpi::uv::Pipe::SetPendingInstances ( int  count)
inline

Set the number of pending pipe instance handles when the pipe server is waiting for connections.

Note
This setting applies to Windows only.
Parameters
countNumber of pending handles.

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