Flow-IPC 1.0.2
Flow-IPC project: Public API.
Public Types | Public Member Functions | Public Attributes | Static Public Attributes | Related Functions | List of all members
ipc::util::Native_handle Struct Reference

A monolayer-thin wrapper around a native handle, a/k/a descriptor a/k/a FD. More...

#include <native_handle.hpp>

Public Types

using handle_t = int
 The native handle type. Much logic relies on this type being light-weight (fast to copy).
 

Public Member Functions

 Native_handle (handle_t native_handle=S_NULL_HANDLE)
 Constructs with given payload; also subsumes no-args construction to mean constructing an object with null() == true. More...
 
 Native_handle (Native_handle &&src)
 Constructs object equal to src, while making src == null(). More...
 
 Native_handle (const Native_handle &src)
 Copy constructor. More...
 
Native_handleoperator= (Native_handle &&src)
 Move assignment; acts similarly to move ctor; but no-op if *this == src. More...
 
Native_handleoperator= (const Native_handle &src)
 Copy assignment; acts similarly to copy ctor. More...
 
bool null () const
 Returns true if and only if m_native_handle equals S_NULL_HANDLE. More...
 

Public Attributes

handle_t m_native_handle
 The native handle (possibly equal to S_NULL_HANDLE), the exact payload of this Native_handle. More...
 

Static Public Attributes

static const handle_t S_NULL_HANDLE = -1
 The value for m_native_handle such that null() == true; else it is false. More...
 

Related Functions

(Note that these are not member functions.)

bool operator== (Native_handle val1, Native_handle val2)
 Returns true if and only if the two Native_handle objects are the same underlying handle. More...
 
bool operator!= (Native_handle val1, Native_handle val2)
 Negation of similar ==. More...
 
bool operator< (Native_handle val1, Native_handle val2)
 Returns a less-than comparison of two Native_handle objects, with the usual total ordering guarantees. More...
 
size_t hash_value (Native_handle val)
 Hasher of Native_handle for boost.unordered et al. More...
 
std::ostream & operator<< (std::ostream &os, const Native_handle &val)
 Prints string representation of the given Native_handle to the given ostream. More...
 

Detailed Description

A monolayer-thin wrapper around a native handle, a/k/a descriptor a/k/a FD.

It would have been acceptable to simply use an alias to the native handle type (in POSIX, int), but this way is better stylistically with exactly zero performance overhead. Initialize it, e.g., Native_handle hndl(some_fd);, where some_fd might be some POSIX-y FD (network socket, Unix domain socket, file descriptor, etc.). Or initialize via no-arg construction which results in an null() == true object. Copy construction, assignment, equality, total ordering, and hashing all work as one would expect and essentially the same as on the underlying native handles.

It is either null() or stores a native handle. In the former case, null() being true means explicitly that m_native_handle == Native_handle::S_NULL_HANDLE.

Rationale

Originally we tried to make it aggregate-initializable, like Native_handle hndl = {some_fd}; for example see standard array<>. This is reassuring perf-wise; and it involves less (i.e., no) code to boot. However, it really is just one light-weight scalar, and there's 0% chance explicit construction is any slower. So, perf isn't an issue. Still, why not make it aggregate-initializable though? I (ygoldfel) gave up, eventually, because I wanted some non-default-behavior constructors to be available, namely no-args (Native_handle() that makes an null() == true one) and move (Native_handle(Native_handle&&) that nullifies the source object). This isn't allowed in aggregate-initializable classes; so then I made some static "constructors" instead; but those aren't sufficient for containers... and on it went. This way, though verbose, just works out better for the API.

Constructor & Destructor Documentation

◆ Native_handle() [1/3]

ipc::util::Native_handle::Native_handle ( handle_t  native_handle = S_NULL_HANDLE)

Constructs with given payload; also subsumes no-args construction to mean constructing an object with null() == true.

Parameters
native_handlePayload.

◆ Native_handle() [2/3]

ipc::util::Native_handle::Native_handle ( Native_handle &&  src)

Constructs object equal to src, while making src == null().

Rationale

This is move construction, but it's not about performance at all (as this is all quite cheap anyway); more to allow for the pattern of making an object from another object without propagating more copies of the underlying handle. Won't the default move ctor take care of it? No, because it'll just copy the handle and not nullify it.

Parameters
srcSource object which will be made null() == true.

◆ Native_handle() [3/3]

ipc::util::Native_handle::Native_handle ( const Native_handle src)
default

Copy constructor.

Parameters
srcSource object.

Member Function Documentation

◆ null()

bool ipc::util::Native_handle::null ( ) const

Returns true if and only if m_native_handle equals S_NULL_HANDLE.

Returns
See above.

◆ operator=() [1/2]

Native_handle & ipc::util::Native_handle::operator= ( const Native_handle src)
default

Copy assignment; acts similarly to copy ctor.

Parameters
srcSource object.
Returns
*this.

◆ operator=() [2/2]

Native_handle & ipc::util::Native_handle::operator= ( Native_handle &&  src)

Move assignment; acts similarly to move ctor; but no-op if *this == src.

Parameters
srcSource object which will be made null() == true, unles *this == src.
Returns
*this.

Friends And Related Function Documentation

◆ hash_value()

size_t hash_value ( Native_handle  val)
related

Hasher of Native_handle for boost.unordered et al.

Parameters
valObject to hash.
Returns
See above.

◆ operator!=()

bool operator!= ( Native_handle  val1,
Native_handle  val2 
)
related

Negation of similar ==.

Parameters
val1Object.
val2Object.
Returns
See above.

◆ operator<()

bool operator< ( Native_handle  val1,
Native_handle  val2 
)
related

Returns a less-than comparison of two Native_handle objects, with the usual total ordering guarantees.

Parameters
val1Left-hand side object.
val2Right-hand side object.
Returns
Whether left side is considered strictly less-than right side.

◆ operator<<()

std::ostream & operator<< ( std::ostream &  os,
const Native_handle val 
)
related

Prints string representation of the given Native_handle to the given ostream.

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

◆ operator==()

bool operator== ( Native_handle  val1,
Native_handle  val2 
)
related

Returns true if and only if the two Native_handle objects are the same underlying handle.

Parameters
val1Object.
val2Object.
Returns
See above.

Member Data Documentation

◆ m_native_handle

handle_t ipc::util::Native_handle::m_native_handle

The native handle (possibly equal to S_NULL_HANDLE), the exact payload of this Native_handle.

It can, of course, be assigned and accessed explicitly. The best way to initialize a new Native_handle is, therefore: Native_handle{some_native_handle}. You may also use the null() "constructor" to create a null() handle.

◆ S_NULL_HANDLE

const Native_handle::handle_t ipc::util::Native_handle::S_NULL_HANDLE = -1
static

The value for m_native_handle such that null() == true; else it is false.

No valid handle ever equals this.


The documentation for this struct was generated from the following files: