Flow-IPC 1.0.2
Flow-IPC project: Public API.
|
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... | |
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
.
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.
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
.
native_handle | Payload. |
ipc::util::Native_handle::Native_handle | ( | Native_handle && | src | ) |
Constructs object equal to src
, while making src == null()
.
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.
src | Source object which will be made null() == true . |
|
default |
Copy constructor.
src | Source object. |
bool ipc::util::Native_handle::null | ( | ) | const |
Returns true
if and only if m_native_handle equals S_NULL_HANDLE.
|
default |
Copy assignment; acts similarly to copy ctor.
src | Source object. |
*this
. Native_handle & ipc::util::Native_handle::operator= | ( | Native_handle && | src | ) |
Move assignment; acts similarly to move ctor; but no-op if *this == src
.
src | Source object which will be made null() == true , unles *this == src . |
*this
.
|
related |
|
related |
Negation of similar ==
.
val1 | Object. |
val2 | Object. |
|
related |
Returns a less-than comparison of two Native_handle objects, with the usual total ordering guarantees.
val1 | Left-hand side object. |
val2 | Right-hand side object. |
|
related |
Prints string representation of the given Native_handle to the given ostream
.
os | Stream to which to write. |
val | Object to serialize. |
os
.
|
related |
Returns true
if and only if the two Native_handle objects are the same underlying handle.
val1 | Object. |
val2 | Object. |
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.
|
static |
The value for m_native_handle such that null() == true
; else it is false
.
No valid handle ever equals this.