WPILibC++ 2024.3.2
wpi::uv::Handle Class Reference

Handle. More...

#include <wpinet/uv/Handle.h>

Inheritance diagram for wpi::uv::Handle:
wpi::uv::HandleImpl< Async< T... >, uv_async_t > wpi::uv::HandleImpl< Async<>, uv_async_t > wpi::uv::HandleImpl< AsyncFunction< R(T...)>, uv_async_t > wpi::uv::HandleImpl< Check, uv_check_t > wpi::uv::HandleImpl< FsEvent, uv_fs_event_t > wpi::uv::HandleImpl< Idle, uv_idle_t > wpi::uv::HandleImpl< Poll, uv_poll_t > wpi::uv::HandleImpl< Prepare, uv_prepare_t > wpi::uv::HandleImpl< Process, uv_process_t > wpi::uv::HandleImpl< Signal, uv_signal_t > wpi::uv::HandleImpl< Timer, uv_timer_t > wpi::uv::HandleImpl< Udp, uv_udp_t > wpi::uv::HandleImpl< T, U > wpi::uv::Stream

Public Types

using Type = uv_handle_type
 

Public Member Functions

 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...
 

Public Attributes

sig::Signal< Errorerror
 Error signal. More...
 
sig::Signal closed
 Closed signal. More...
 

Protected Member Functions

 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

static void AllocBuf (uv_handle_t *handle, size_t size, uv_buf_t *buf)
 
static void DefaultFreeBuf (Buffer &buf)
 

Detailed Description

Handle.

Handles are not moveable or copyable and cannot be directly constructed. This class provides shared_ptr ownership and shared_from_this. Use the specific handle type Create() functions to create handles.

Member Typedef Documentation

◆ Type

Constructor & Destructor Documentation

◆ Handle() [1/3]

wpi::uv::Handle::Handle ( const Handle )
delete

◆ Handle() [2/3]

wpi::uv::Handle::Handle ( Handle &&  )
delete

◆ ~Handle()

virtual wpi::uv::Handle::~Handle ( )
virtualnoexcept

◆ Handle() [3/3]

wpi::uv::Handle::Handle ( uv_handle_t uv_handle)
inlineexplicitprotected

Member Function Documentation

◆ AllocBuf()

static void wpi::uv::Handle::AllocBuf ( uv_handle_t handle,
size_t  size,
uv_buf_t buf 
)
staticprotected

◆ Close()

void wpi::uv::Handle::Close ( )
noexcept

Request handle to be closed.

This must be called on each handle before memory is released. In-progress requests are cancelled and this can result in error() being emitted.

The handle will emit closed() when finished.

◆ DefaultFreeBuf()

static void wpi::uv::Handle::DefaultFreeBuf ( Buffer buf)
staticprotected

◆ ForceClosed()

void wpi::uv::Handle::ForceClosed ( )
inlineprotectednoexcept

◆ FreeBuf()

void wpi::uv::Handle::FreeBuf ( Buffer buf) const
inlinenoexcept

Free a buffer.

Uses the function provided to SetBufFree() or Buffer::Deallocate by default.

Parameters
bufThe buffer

◆ GetData()

template<typename T = void>
std::shared_ptr< T > wpi::uv::Handle::GetData ( ) const
inline

Gets user-defined data.

Returns
User-defined data if any, nullptr otherwise.

◆ GetLogger()

Logger * wpi::uv::Handle::GetLogger ( ) const
inline

Gets logger.

Returns
Logger, or nullptr if none set

◆ GetLoop()

std::shared_ptr< Loop > wpi::uv::Handle::GetLoop ( ) const
inlinenoexcept

Get the loop where this handle runs.

Returns
The loop.

◆ GetLoopRef()

Loop & wpi::uv::Handle::GetLoopRef ( ) const
inlinenoexcept

Get the loop where this handle runs.

Returns
The loop.

◆ GetRawHandle()

uv_handle_t * wpi::uv::Handle::GetRawHandle ( ) const
inlinenoexcept

Get the underlying handle data structure.

Returns
The underlying handle data structure.

◆ GetType()

Type wpi::uv::Handle::GetType ( ) const
inlinenoexcept

Get the type of the handle.

A base handle offers no functionality to promote it to the actual handle type. By means of this function, the type of the underlying handle as specified by Type is made available.

Returns
The actual type of the handle.

◆ GetTypeName()

std::string_view wpi::uv::Handle::GetTypeName ( ) const
inlinenoexcept

Get the name of the type of the handle.

E.g. "pipe" for pipe handles.

◆ HasReference()

bool wpi::uv::Handle::HasReference ( ) const
inlinenoexcept

Check if the given handle is referenced.

Returns
True if the handle is referenced, false otherwise.

◆ Invoke()

template<typename F , typename... Args>
bool wpi::uv::Handle::Invoke ( F &&  f,
Args &&...  args 
) const
inlineprotected

◆ IsActive()

bool wpi::uv::Handle::IsActive ( ) const
inlinenoexcept

Check if the handle is active.

What active means depends on the type of handle:

  • An AsyncHandle handle is always active and cannot be deactivated, except by closing it with uv_close().
  • A PipeHandle, TcpHandle, UDPHandle, etc. handle - basically any handle that deals with I/O - is active when it is doing something that involves I/O, like reading, writing, connecting, accepting new connections, etc.
  • A CheckHandle, IdleHandle, TimerHandle, etc. handle is active when it has been started with a call to Start().

Rule of thumb: if a handle of type FooHandle has a Start() member method, then it’s active from the moment that method is called. Likewise, Stop() deactivates the handle again.

Returns
True if the handle is active, false otherwise.

◆ IsClosing()

bool wpi::uv::Handle::IsClosing ( ) const
inlinenoexcept

Check if a handle is closing or closed.

This function should only be used between the initialization of the handle and the arrival of the close callback.

Returns
True if the handle is closing or closed, false otherwise.

◆ IsLoopClosing()

bool wpi::uv::Handle::IsLoopClosing ( ) const
inlinenoexcept

Get the loop closing status.

This can be used from closed() in order to tell if a closing loop is the reason for the close, or another reason.

Returns
true if the loop is closing, otherwise false.

◆ Keep()

void wpi::uv::Handle::Keep ( )
inlineprotectednoexcept

◆ operator=() [1/2]

Handle & wpi::uv::Handle::operator= ( const Handle )
delete

◆ operator=() [2/2]

Handle & wpi::uv::Handle::operator= ( Handle &&  )
delete

◆ RawSize()

size_t wpi::uv::Handle::RawSize ( ) const
inlinenoexcept

Return the size of the underlying handle type.

Returns
The size of the underlying handle type.

◆ Reference()

void wpi::uv::Handle::Reference ( )
inlinenoexcept

Reference the given handle.

References are idempotent, that is, if a handle is already referenced calling this function again will have no effect.

◆ Release()

void wpi::uv::Handle::Release ( )
inlineprotectednoexcept

◆ ReportError()

void wpi::uv::Handle::ReportError ( int  err) const
inline

Report an error.

Parameters
errError code

◆ SetBufferAllocator()

void wpi::uv::Handle::SetBufferAllocator ( std::function< Buffer(size_t)>  alloc,
std::function< void(Buffer &)>  dealloc 
)
inline

Set the functions used for allocating and releasing buffers.

The size passed to the allocator function is a "suggested" size–it's just an indication, not related in any way to the pending data to be read. The user is free to allocate the amount of memory they decide. For example, applications with custom allocation schemes may decide to use a different size which matches the memory chunks they already have for other purposes.

Warning
Be very careful changing the allocator after the loop has started running; there are no interlocks between this and buffers currently in flight.
Parameters
allocAllocation function
deallocDeallocation function

◆ SetData()

void wpi::uv::Handle::SetData ( std::shared_ptr< void >  data)
inline

Sets user-defined data.

Parameters
dataUser-defined arbitrary data.

◆ SetLogger()

void wpi::uv::Handle::SetLogger ( Logger logger)
inline

Sets logger.

Parameters
loggerLogger

◆ SetLoopClosing()

void wpi::uv::Handle::SetLoopClosing ( bool  loopClosing)
inlinenoexcept

Set if the loop is closing.

This is set during EventLoopRunner.Stop(), and can be used for other cases to indicate the loop should be closing. For instance for a uv_walk loop can use this to close existing handles.

Parameters
loopClosingtrue to set the loop currently in closing stages.

◆ Unreference()

void wpi::uv::Handle::Unreference ( )
inlinenoexcept

Unreference the given handle.

References are idempotent, that is, if a handle is not referenced calling this function again will have no effect.

Member Data Documentation

◆ closed

sig::Signal wpi::uv::Handle::closed

Closed signal.

◆ error

sig::Signal<Error> wpi::uv::Handle::error

Error signal.


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