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>

Collaboration diagram for ipc::util::Native_handle:

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

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.

Definition at line 61 of file native_handle.hpp.

Member Typedef Documentation

handle_t

using ipc::util::Native_handle::handle_t = int

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

Definition at line 66 of file native_handle.hpp.

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.

Definition at line 32 of file native_handle.cpp.

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.

Definition at line 38 of file native_handle.cpp.

References operator=().

Here is the call graph for this function:

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.

Definition at line 60 of file native_handle.cpp.

References m_native_handle, and S_NULL_HANDLE.

Referenced by ipc::transport::Posix_mq_handle::allow_impl(), ipc::util::sync_io::Asio_waitable_native_handle::Asio_waitable_native_handle(), ipc::util::sync_io::Asio_waitable_native_handle::assign(), ipc::transport::asio_local_stream_socket::async_write_with_native_handle(), ipc::session::ensure_resource_owner_is_app(), ipc::transport::Posix_mq_handle::interrupt_impl(), ipc::transport::Posix_mq_handle::max_msg_size(), ipc::transport::Posix_mq_handle::max_n_msgs(), ipc::transport::Native_socket_stream_acceptor::on_next_peer_socket_or_error(), operator<<(), ipc::transport::Posix_mq_handle::Posix_mq_handle(), ipc::transport::struc::sync_io::Channel< Channel_obj, Message_body, Struct_builder_config, Struct_reader_config >::rcv_async_read_lead_or_continuation_msg(), ipc::transport::sync_io::Native_socket_stream::Impl::rcv_nb_read_low_lvl_payload(), ipc::transport::struc::sync_io::Channel< Channel_obj, Message_body, Struct_builder_config, Struct_reader_config >::rcv_on_async_read_continuation_msg(), ipc::transport::struc::sync_io::Channel< Channel_obj, Message_body, Struct_builder_config, Struct_reader_config >::rcv_on_async_read_lead_msg(), ipc::transport::struc::sync_io::Channel< Channel_obj, Message_body, Struct_builder_config, Struct_reader_config >::rcv_on_async_read_proto_neg_msg(), ipc::transport::sync_io::Native_socket_stream::Impl::rcv_on_handle_finalized(), ipc::transport::Posix_mq_handle::receive(), ipc::transport::Posix_mq_handle::send(), ipc::transport::sync_io::Native_socket_stream::Impl::send_native_handle(), ipc::util::set_resource_permissions(), ipc::transport::sync_io::Native_socket_stream::Impl::snd_nb_write_low_lvl_payload(), ipc::transport::sync_io::Native_socket_stream::Impl::snd_sync_write_or_q_payload(), ipc::transport::Posix_mq_handle::timed_receive(), ipc::transport::Posix_mq_handle::timed_send(), ipc::transport::Posix_mq_handle::try_receive(), ipc::transport::Posix_mq_handle::try_send(), ipc::transport::Posix_mq_handle::wait_impl(), and ipc::transport::Posix_mq_handle::~Posix_mq_handle().

Here is the caller graph for this function:

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.

Definition at line 46 of file native_handle.cpp.

References m_native_handle, S_NULL_HANDLE, ipc::transport::swap(), and ipc::util::swap().

Referenced by Native_handle().

Here is the call graph for this function:

Here is the caller graph for this function:

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

val	Object to hash.

Returns

See above.

Definition at line 89 of file native_handle.cpp.

References m_native_handle.

operator!=()

bool operator!= ( Native_handle  val1, Native_handle  val2  )

related

Negation of similar ==.

Parameters

val1	Object.
val2	Object.

Returns

See above.

Definition at line 84 of file native_handle.cpp.

References ipc::util::operator==().

Here is the call graph for this function:

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

val1	Left-hand side object.
val2	Right-hand side object.

Returns

Whether left side is considered strictly less-than right side.

Definition at line 96 of file native_handle.cpp.

References m_native_handle.

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

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

Returns

os.

Definition at line 65 of file native_handle.cpp.

References m_native_handle, and null().

Here is the call graph for this function:

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

val1	Object.
val2	Object.

Returns

See above.

Definition at line 79 of file native_handle.cpp.

References m_native_handle.

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.

Definition at line 84 of file native_handle.hpp.

Referenced by ipc::util::sync_io::Asio_waitable_native_handle::assign(), ipc::session::ensure_resource_owner_is_app(), ipc::transport::Posix_mq_handle::epoll_setup(), hash_value(), ipc::transport::Posix_mq_handle::max_msg_size(), ipc::transport::Posix_mq_handle::max_n_msgs(), ipc::transport::asio_local_stream_socket::nb_write_some_with_native_handle(), null(), operator<(), operator<<(), operator=(), operator==(), ipc::transport::Posix_mq_handle::Posix_mq_handle(), ipc::transport::Posix_mq_handle::receive(), ipc::transport::sync_io::Blob_stream_mq_receiver_impl< Persistent_mq_handle >::replace_event_wait_handles(), ipc::transport::sync_io::Blob_stream_mq_sender_impl< Persistent_mq_handle >::replace_event_wait_handles(), ipc::transport::sync_io::Native_socket_stream::Impl::replace_event_wait_handles(), ipc::transport::Posix_mq_handle::send(), ipc::transport::Posix_mq_handle::set_non_blocking(), ipc::util::set_resource_permissions(), ipc::transport::Posix_mq_handle::timed_receive(), ipc::transport::Posix_mq_handle::timed_send(), ipc::transport::Posix_mq_handle::try_receive(), ipc::transport::Posix_mq_handle::try_send(), ipc::transport::Posix_mq_handle::wait_impl(), and ipc::transport::Posix_mq_handle::~Posix_mq_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.

Definition at line 74 of file native_handle.hpp.

Referenced by null(), and operator=().

---

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

• util/native_handle.hpp
• util/native_handle.cpp