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_handle &	operator= (Native_handle &&src)
	Move assignment; acts similarly to move ctor; but no-op if `*this == src`. More...

Native_handle &	operator= (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_handle Payload.

◆ 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

src	Source 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

src	Source 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

src	Source 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

src	Source 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 )

Parameters

val	Object to hash.

Returns: See above.

◆ operator!=()

bool operator!=	(	Native_handle	val1,
		Native_handle	val2
	)

Parameters

val1	Object.
val2	Object.

Returns: See above.

◆ operator<()

bool operator<	(	Native_handle	val1,
		Native_handle	val2
	)

Parameters

val1	Left-hand side object.
val2	Right-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
	)

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator==()

bool operator==	(	Native_handle	val1,
		Native_handle	val2
	)

Parameters

val1	Object.
val2	Object.

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:

util/native_handle.hpp
util/native_handle.cpp

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Related Functions

Detailed Description

Rationale

Constructor & Destructor Documentation

◆ Native_handle() [1/3]

◆ Native_handle() [2/3]

Rationale

◆ Native_handle() [3/3]

Member Function Documentation

◆ null()

◆ operator=() [1/2]

◆ operator=() [2/2]

Friends And Related Function Documentation

◆ hash_value()

◆ operator!=()

◆ operator<()

◆ operator<<()

◆ operator==()

Member Data Documentation

◆ m_native_handle

◆ S_NULL_HANDLE