Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-IPC modules and/or do not fit into any other Flow-IPC module. More...

Namespaces
namespace	sync_io
	Contains common code, as well as important explanatory documentation in the following text, for the `sync_io` pattern used in ipc::transport and ipc::session to provide fine-tuned control over integrating asynchronous Flow-IPC activities into the user's event loop.

Classes
class	Default_init_allocator
	Allocator adaptor (useful for, e.g., `vector` that skips zero-filling) that turns a value-initialization `T()` into a default-initialization for those types, namely PoDs, for which default-initialization is a no-op. More...

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

class	Process_credentials
	A process's credentials (PID, UID, GID as of this writing). More...

class	Shared_name
	String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity from all others in the system, or a fragment of such a name. More...

class	Use_counted_object
	Simple counter that manually tracks utilization. It is not thread-safe. More...

Typedefs
using	Pipe_writer = boost::asio::writable_pipe
	Short-hand for anonymous pipe write end. More...

using	Pipe_reader = boost::asio::readable_pipe
	Short-hand for anonymous pipe read end. More...

using	String_view = flow::util::String_view
	Short-hand for Flow's `String_view`. More...

using	Fine_duration = flow::Fine_duration
	Short-hand for Flow's `Fine_duration`. More...

using	Fine_time_pt = flow::Fine_time_pt
	Short-hand for Flow's `Fine_time_pt`. More...

using	Task = flow::async::Task
	Short-hand for polymorphic function (a-la `std::function<>`) that takes no arguments and returns nothing. More...

using	Blob_const = boost::asio::const_buffer
	Short-hand for an immutable blob somewhere in memory, stored as exactly a `void const *` and a `size_t`. More...

using	Blob_mutable = boost::asio::mutable_buffer
	Short-hand for an mutable blob somewhere in memory, stored as exactly a `void*` and a `size_t`. More...

using	process_id_t = ::pid_t
	Syntactic-sugary type for POSIX process ID (integer). More...

using	user_id_t = ::uid_t
	Syntactic-sugary type for POSIX user ID (integer). More...

using	group_id_t = ::gid_t
	Syntactic-sugary type for POSIX group ID (integer). More...

using	Open_or_create = bipc::open_or_create_t
	Tag type indicating an atomic open-if-exists-else-create operation. More...

using	Open_only = bipc::open_only_t
	Tag type indicating an ideally-atomic open-if-exists-else-fail operation. More...

using	Create_only = bipc::create_only_t
	Tag type indicating a create-unless-exists-else-fail operation. More...

using	Permissions = bipc::permissions
	Short-hand for Unix (POSIX) permissions class. More...

Enumerations
enum class	Permissions_level : size_t { S_NO_ACCESS , S_USER_ACCESS , S_GROUP_ACCESS , S_UNRESTRICTED , S_END_SENTINEL }
	Simple specifier of desired access permissions, usually but not necessarily translated into a `Permissions` value (though even then different value in different contexts). More...

Functions
void	pipe_produce (flow::log::Logger logger_ptr, Pipe_writer pipe)
	Writes a byte to the given pipe writer. More...

void	pipe_consume (flow::log::Logger logger_ptr, Pipe_reader pipe)
	Reads a byte via the given pipe reader. More...

void	remove_persistent_shm_pool (flow::log::Logger logger_ptr, const Shared_name &name, Error_code err_code)
	Equivalent to shm::classic::Pool_arena::remove_persistent(). More...

template<typename Func >
void	op_with_possible_bipc_exception (flow::log::Logger logger_ptr, Error_code err_code, const Error_code &misc_bipc_lib_error, String_view context, const Func &func)
	Internal (to ipc) utility that invokes the given function that invokes a boost.interprocess operation that is documented to throw `bipc::interprocess_exception` on failure; if indeed it throws the utility emits an error in the Flow error-reporting style. More...

template<typename Handle_name_func >
void	for_each_persistent_impl (const fs::path &persistent_obj_dev_dir_path, const Handle_name_func &handle_name_func)
	Implementation of `Persistent_object::for_each_persistent()`; for example see shm::classic::Pool_arena::for_each_persistent(). More...

template<typename Handle_name_func >
void	for_each_persistent_shm_pool (const Handle_name_func &handle_name_func)
	Equivalent to shm::classic::Pool_arena::for_each_persistent(). More...

Shared_name	build_conventional_non_session_based_shared_name (const Shared_name &resource_type)
	Builds an absolute name according to the path convention explained in Shared_name class doc header; this overload applies to resources outside the ipc::session paradigm. More...

std::ostream &	operator<< (std::ostream &os, const Native_handle &val)
	Prints string representation of the given Native_handle to the given `ostream`. More...

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

size_t	hash_value (Native_handle val)
	Hasher of Native_handle for boost.unordered et al. 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...

bool	operator== (const Process_credentials &val1, const Process_credentials &val2)
	Checks for by-value equality between two Process_credentials objects. More...

bool	operator!= (const Process_credentials &val1, const Process_credentials &val2)
	Checks for by-value inequality between two Process_credentials objects. More...

std::ostream &	operator<< (std::ostream &os, const Process_credentials &val)
	Prints string representation of the given util::Process_credentials to the given `ostream`. More...

Shared_name	operator+ (const Shared_name &src1, const char *raw_src2)
	Returns new object equal to `Shared_name(src1) += raw_src2`. More...

Shared_name	operator+ (const char *raw_src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(src2)` with `raw_src1` pre-pended to it. More...

Shared_name	operator+ (const Shared_name &src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(src1) += src2`. More...

Shared_name	operator/ (const Shared_name &src1, const char *raw_src2)
	Returns new object equal to `Shared_name(src1) /= raw_src2`. More...

Shared_name	operator/ (const char *raw_src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(raw_src1) /= src2`. More...

Shared_name	operator/ (const Shared_name &src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(src1) /= src2`. More...

std::ostream &	operator<< (std::ostream &os, const Shared_name &val)
	Prints embellished string representation of the given Shared_name to the given `ostream`. More...

std::istream &	operator>> (std::istream &is, Shared_name &val)
	Reads Shared_name from the given `istream`; equivalent to reading `string` into Shared_name::str(). More...

bool	operator== (const Shared_name &val1, const Shared_name &val2)
	Returns `true` if and only if `val1.str() == val2.str()`. More...

bool	operator!= (const Shared_name &val1, const Shared_name &val2)
	Negation of similar `==`. More...

bool	operator== (const Shared_name &val1, util::String_view val2)
	Returns `true` if and only if `val1.str() == string(val2)`. More...

bool	operator!= (const Shared_name &val1, util::String_view val2)
	Negation of similar `==`. More...

bool	operator== (util::String_view val1, const Shared_name &val2)
	Returns `true` if and only if `string(val1) == val2.str()`. More...

bool	operator!= (util::String_view val1, const Shared_name &val2)
	Negation of similar `==`. More...

bool	operator< (const Shared_name &val1, const Shared_name &val2)
	Returns `true` if and only if `val1.str() < val2.str()`. More...

size_t	hash_value (const Shared_name &val)
	Hasher of Shared_name for boost.unordered et al. More...

void	swap (Shared_name &val1, Shared_name &val2)
	Swaps two objects. More...

template<typename Source >
Shared_name	operator+ (const Shared_name &src1, const Source &raw_src2)
	Returns new object equal to `Shared_name(src1) += raw_src2`. More...

template<typename Source >
Shared_name	operator+ (const Source &raw_src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(src2)` with `raw_src1` pre-pended to it. More...

template<typename Source >
Shared_name	operator/ (const Shared_name &src1, const Source &raw_src2)
	Returns new object equal to `Shared_name(src1) /= raw_src2`. More...

template<typename Source >
Shared_name	operator/ (const Source &raw_src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(raw_src1) /= src2`. More...

template<typename Persistent_object , typename Filter_func >
unsigned int	remove_each_persistent_if (flow::log::Logger *logger_ptr, const Filter_func &filter_func)
	Utility that invokes `Persistent_object::for_each_persistent(name_prefix_or_empty)` and synchronously invokes `Persistent_object::remove_persistent()` on each resulting item that passes the given filter, where `Persistent_object` is a type that handles objects – such as SHM pools or POSIX MQs – with kernel-persistent semantics. More...

template<typename Persistent_object >
unsigned int	remove_each_persistent_with_name_prefix (flow::log::Logger *logger_ptr, const Shared_name &name_prefix_or_empty)
	Utility that invokes remove_each_persistent_if() with the filter that returns `true` (yes, remove) if and only if the item's name optionally matches a given Shared_name prefix. More...

Permissions	shared_resource_permissions (Permissions_level permissions_lvl)
	Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource is in the file-system and is either accessible (read-write in terms of file system) or inaccessible. More...

void	set_resource_permissions (flow::log::Logger logger_ptr, const fs::path &path, const Permissions &perms, Error_code err_code=0)
	Utility that sets the permissions of the given resource (at the supplied file system path) to specified POSIX value. More...

void	set_resource_permissions (flow::log::Logger logger_ptr, Native_handle handle, const Permissions &perms, Error_code err_code=0)
	Identical to the other set_resource_permissions() overload but operates on a pre-opened Native_handle (a/k/a handle, socket, file descriptor) to the resource in question. More...

bool	process_running (process_id_t process_id)
	Returns `true` if and only if the given process (by PID) is reported as running by the OS. More...

const uint8_t *	blob_data (const Blob_const &blob)
	Syntactic-sugary helper that returns pointer to first byte in an immutable buffer, as `const uint8_t*`. More...

uint8_t *	blob_data (const Blob_mutable &blob)
	Syntactic-sugary helper that returns pointer to first byte in a mutable buffer, as `uint8_t*`. More...

Variables
const boost::array< Permissions, size_t(Permissions_level::S_END_SENTINEL)>	SHARED_RESOURCE_PERMISSIONS_LVL_MAP
	Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource is in the file-system and is either accessible (read-write in terms of file system) or inaccessible. More...

const boost::array< Permissions, size_t(Permissions_level::S_END_SENTINEL)>	PRODUCER_CONSUMER_RESOURCE_PERMISSIONS_LVL_MAP
	Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource is in the file-system (e.g., a file) and is produced (and therefore always writable) by the owning (creating, updating) user; but consumed (and therefore at most readable, never writable) by potentially other processes, and therefore possibly other users (e.g., group access or unrestricted access – but only for reading either way). More...

const fs::path	IPC_KERNEL_PERSISTENT_RUN_DIR = "/var/run"
	Absolute path to the directory (without trailing separator) in the file system where kernel-persistent runtime, but not temporary, information shall be placed. More...

const Open_or_create	OPEN_OR_CREATE
	Tag value indicating an open-if-exists-else-create operation. More...

const Open_only	OPEN_ONLY
	Tag value indicating an atomic open-if-exists-else-fail operation. More...

const Create_only	CREATE_ONLY
	Tag value indicating an atomic create-unless-exists-else-fail operation. More...

const std::string	EMPTY_STRING
	A (default-cted) string. May be useful for functions returning `const std::string&`. More...

Detailed Description

Flow-IPC module containing miscellaneous general-use facilities that ubiquitously used by ~all Flow-IPC modules and/or do not fit into any other Flow-IPC module.

Each symbol therein is typically used by at least 1 other Flow-IPC module; but all public symbols (except ones under a detail/ subdirectory) are intended for use by Flow-IPC user as well. Some particulars to note:

ipc::util::Shared_name is a universally used shared-resource name class, conceptually similar to boost::filesystem::path. It is used in ipc::transport APIs – namely to name endpoints when establishing channels, and more – but also in other Flow-IPC modules. For example Shared_name is used to name certain SHM entities in ipc::shm and in ipc::session when connecting to conversation partner process(es).

ipc::util::Native_handle is a commonly used native-handle (FD in POSIX parlance) wrapper (so thin it doesn't add a single bit on top of the actul FD). These are ~always passed around by value (copied), as they are very small in practice.

There are of course various other things; just check them out as they are referenced, or just look around. Note there are free functions providing various niceties; and more types including classes and scoped enums.

Typedef Documentation

◆ Blob_const

using ipc::util::Blob_const = typedef boost::asio::const_buffer

Short-hand for an immutable blob somewhere in memory, stored as exactly a void const * and a size_t.

How to use

We provide this alias as a stylistic short-hand, as it better suits various interfaces especially in ipc::transport. Nevertheless it's not meant to more than that; it's an attempt to abstract it away.

That is to say, to work with these (create them, access them, etc.), do use the highly convenient boost.asio buffer APIs which are well documented in boost.asio's docs.

Definition at line 128 of file util_fwd.hpp.

◆ Blob_mutable

using ipc::util::Blob_mutable = typedef boost::asio::mutable_buffer

Short-hand for an mutable blob somewhere in memory, stored as exactly a void* and a size_t.

See also: ipc::util::Blob_const; usability notes in that doc header apply similarly here.

Definition at line 134 of file util_fwd.hpp.

◆ Create_only

using ipc::util::Create_only = typedef bipc::create_only_t

Tag type indicating a create-unless-exists-else-fail operation.

See also: CREATE_ONLY.

Definition at line 152 of file util_fwd.hpp.

◆ Fine_duration

using ipc::util::Fine_duration = typedef flow::Fine_duration

Short-hand for Flow's Fine_duration.

Definition at line 111 of file util_fwd.hpp.

◆ Fine_time_pt

using ipc::util::Fine_time_pt = typedef flow::Fine_time_pt

Short-hand for Flow's Fine_time_pt.

Definition at line 113 of file util_fwd.hpp.

◆ group_id_t

using ipc::util::group_id_t = typedef ::gid_t

Syntactic-sugary type for POSIX group ID (integer).

Definition at line 143 of file util_fwd.hpp.

◆ Open_only

using ipc::util::Open_only = typedef bipc::open_only_t

Tag type indicating an ideally-atomic open-if-exists-else-fail operation.

See also: OPEN_ONLY.

Definition at line 149 of file util_fwd.hpp.

◆ Open_or_create

using ipc::util::Open_or_create = typedef bipc::open_or_create_t

Tag type indicating an atomic open-if-exists-else-create operation.

See also: OPEN_OR_CREATE.

Definition at line 146 of file util_fwd.hpp.

◆ Permissions

using ipc::util::Permissions = typedef bipc::permissions

Short-hand for Unix (POSIX) permissions class.

Definition at line 155 of file util_fwd.hpp.

◆ Pipe_reader

using ipc::util::Pipe_reader = typedef boost::asio::readable_pipe

Short-hand for anonymous pipe read end.

Definition at line 35 of file util_fwd.hpp.

◆ Pipe_writer

using ipc::util::Pipe_writer = typedef boost::asio::writable_pipe

Short-hand for anonymous pipe write end.

Definition at line 32 of file util_fwd.hpp.

◆ process_id_t

using ipc::util::process_id_t = typedef ::pid_t

Syntactic-sugary type for POSIX process ID (integer).

Definition at line 137 of file util_fwd.hpp.

◆ String_view

using ipc::util::String_view = typedef flow::util::String_view

Short-hand for Flow's String_view.

Definition at line 109 of file util_fwd.hpp.

◆ Task

using ipc::util::Task = typedef flow::async::Task

Short-hand for polymorphic function (a-la std::function<>) that takes no arguments and returns nothing.

Definition at line 116 of file util_fwd.hpp.

◆ user_id_t

using ipc::util::user_id_t = typedef ::uid_t

Syntactic-sugary type for POSIX user ID (integer).

Definition at line 140 of file util_fwd.hpp.

Enumeration Type Documentation

◆ Permissions_level

enum class ipc::util::Permissions_level : size_t

strong

Simple specifier of desired access permissions, usually but not necessarily translated into a Permissions value (though even then different value in different contexts).

May be used to map, say, from a Permissions_level to a Permissions value in an array<Permissions, size_t(Permissions_level::S_END_SENTINEL)>.

While, unlike Permissions, this enum intends not be overtly based on a POSIX RWXRWXRWC model, it does still assume the 3 user groupings are "user themselves," "user's group," and "everyone." The 1st and 3rd are likely universal, but the 2nd may not apply to all OS – through probably all POSIX/Unix ones – and even for something like Linux there could be different groupings such as ones based on OS ACL. As of this writing it's fine, as this is a POSIX-targeted library at least (in fact, Linux, as of this writing, but that could change to include, say, MacOS/BSD).

Maintenance

Do not change the order of these constants unless absolutely necessary. In general any change here means updating any array<>s (etc.) that map implicitly from a size_t representing Permissions_level. By convention they are named *_PERMISSIONS_LVL_MAP as of this writing.

The array<> mapping scheme is for max performance; if one uses an unordered_map or similar, then there is no similar issue.

Enumerator
S_NO_ACCESS	Forbids all access, even by the creator's user. Most likely this would be useful for testing or debugging.
S_USER_ACCESS	Allows access by resource-owning user (in POSIX/Unix identified by UID) and no one else.
S_GROUP_ACCESS	Allows access by resource-owning user's containing group(s) (in POSIX/Unix identified by GID) and no one else. This implies, as well, at least as much access as `S_USER_ACCESS`.
S_UNRESTRICTED	Allows access by all. Implies, as well, at least as much access as `S_GROUP_ACCESS` and thus `S_USER_ACCESS`.
S_END_SENTINEL	Sentinel: not a valid value. May be used to, e.g., size an `array<>` mapping from Permissions_level.

Definition at line 87 of file util_fwd.hpp.

Function Documentation

◆ blob_data() [1/2]

const uint8_t * ipc::util::blob_data ( const Blob_const & blob )

Syntactic-sugary helper that returns pointer to first byte in an immutable buffer, as const uint8_t*.

Parameters

blob	The buffer.

Returns: See above.

Definition at line 156 of file util.cpp.

Referenced by ipc::transport::asio_local_stream_socket::async_write_with_native_handle(), ipc::transport::asio_local_stream_socket::on_wait_writable_or_error(), ipc::transport::Bipc_mq_handle::send(), ipc::transport::Posix_mq_handle::send(), ipc::transport::Bipc_mq_handle::timed_send(), ipc::transport::Posix_mq_handle::timed_send(), ipc::transport::Bipc_mq_handle::try_send(), and ipc::transport::Posix_mq_handle::try_send().

Here is the caller graph for this function:

◆ blob_data() [2/2]

uint8_t * ipc::util::blob_data ( const Blob_mutable & blob )

Syntactic-sugary helper that returns pointer to first byte in a mutable buffer, as uint8_t*.

Parameters

blob	The buffer.

Returns: See above.

Definition at line 168 of file util.cpp.

◆ build_conventional_non_session_based_shared_name()

Shared_name ipc::util::build_conventional_non_session_based_shared_name ( const Shared_name & resource_type )

Builds an absolute name according to the path convention explained in Shared_name class doc header; this overload applies to resources outside the ipc::session paradigm.

Typically one would then add a Shared_name::S_SEPARATOR and then purpose-specific path component(s) (via /= or similar).

Behavior is undefined if a path fragment argument is empty (assertion may trip).

Parameters

resource_type Resource type constant. Typically it is available as a S_RESOURCE_TYPE_ID constant in some class; otherwise as a Shared_name::S_RESOURCE_TYPE_ID_* constant.

Returns: Absolute path not ending in S_SEPARATOR, typically to be appended with a S_SEPARATOR and more component(s) by the caller.

Definition at line 337 of file shared_name.cpp.

References ipc::util::Shared_name::empty(), ipc::util::Shared_name::S_ROOT_MAGIC, and ipc::util::Shared_name::S_SENTINEL.

Referenced by ipc::transport::Blob_stream_mq_base_impl< Persistent_mq_handle >::mq_sentinel_name().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ for_each_persistent_impl()

template<typename Handle_name_func >

void ipc::util::for_each_persistent_impl	(	const fs::path &	persistent_obj_dev_dir_path,
		const Handle_name_func &	handle_name_func
	)

Implementation of Persistent_object::for_each_persistent(); for example see shm::classic::Pool_arena::for_each_persistent().

It relies on the OS feature wherein each particular Persistent_object (kernel-persistent object) type is listed in flat fashion in a particular directory; persistent_obj_dev_dir_path must specify this directory.

Conceptually, we shall perform ls D/, where D is persistent_obj_dev_dir_path. Then for each resulting D/N, we shall call handle_name_func(N).

Errors (or lack thereof)

There is no error condition. If persistent_obj_dev_dir_path does not exist, or we lack permissions to look therein, it merely means it cannot contain any relevant items; hence handle_name_func() is not invoked.

Template Parameters

Handle_name_func See, e.g., shm::classic::Pool_arena::for_each_persistent().

Parameters

persistent_obj_dev_dir_path	This must be an absolute path, or behavior is undefined (assertion may trip). See above.
handle_name_func	See `Handle_name_func`.

Definition at line 90 of file util.hpp.

References ipc::util::Shared_name::ct().

Referenced by ipc::transport::Posix_mq_handle::for_each_persistent(), and for_each_persistent_shm_pool().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ for_each_persistent_shm_pool()

template<typename Handle_name_func >

void ipc::util::for_each_persistent_shm_pool ( const Handle_name_func & handle_name_func )

Equivalent to shm::classic::Pool_arena::for_each_persistent().

Provided here (for internal purposes as of this writing) to avoid a little circular-inter-component-dependent problem: Posix_mq_handle::for_each_persistent() needs us; but accessing Pool_arena would mean ipc_core Flow-IPC sub-component needing ipc_shm sub-component as a dependency... but the reverse is already naturally the case. See ipc namespace doc header for discussion of the component hierarchy and how we prefer to avoid circular dependencies therein.

Template Parameters

Handle_name_func See above.

Parameters

handle_name_func See above.

Definition at line 130 of file util.hpp.

References for_each_persistent_impl().

Referenced by ipc::transport::Bipc_mq_handle::for_each_persistent(), and ipc::shm::classic::Pool_arena::for_each_persistent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ hash_value() [1/2]

size_t hash_value ( const Shared_name & val )

Hasher of Shared_name for boost.unordered et al.

Parameters

val	Object to hash.

Returns: See above.

Definition at line 412 of file shared_name.cpp.

◆ hash_value() [2/2]

size_t hash_value ( Native_handle val )

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.

◆ op_with_possible_bipc_exception()

template<typename Func >

void ipc::util::op_with_possible_bipc_exception	(	flow::log::Logger *	logger_ptr,
		Error_code *	err_code,
		const Error_code &	misc_bipc_lib_error,
		String_view	context,
		const Func &	func
	)

Internal (to ipc) utility that invokes the given function that invokes a boost.interprocess operation that is documented to throw bipc::interprocess_exception on failure; if indeed it throws the utility emits an error in the Flow error-reporting style.

On error it logs WARNING with all available details.

Background

boost.interprocess has a number of operations that are documented to throw the aforementioned exception on error – without any alternate way of reporting an error such as through an out-arg. Moreover the exception itself is not any standard runtime-exception type but rather a custom thing. This is somewhat annoying; and various parts of ipc want to emit errors in a consistent way. That does not mean we must only emit some transport::error::Code::* or whatever, but we should emit a native-based Error_code if applicable, either as an out-arg or as a flow::error::Runtime_error wrapping it, or indeed one of our own codes otherwise (or if it is more applicable).

So this helper standardizes that stuff.

Template Parameters

Func	Functor that takes no args and returns nothing.

Parameters

logger_ptr	Logger to use for logging subsequently.
err_code	`err_code` as-if passed to our API. `*err_code` shall be set if not null depending on success/failure; if null and no problem, won't throw; if null and problem will throw `Runtime_error` containing a truthy Error_code. That's the usual Flow-style error emission semantics.
misc_bipc_lib_error	If `func` throws, and we are unable to suss out the system error that caused it, then emit this value. E.g.: transport::Code::S_MQ_BIPC_MISC_LIBRARY_ERROR makes sense if creating a `bipc::message_queue`; or a similar one for SHM-related parts of `bipc`; etc.
context	Description for logging of the op being attempted, in case there is an error. Compile-time-known strings are best, as this is not protected by a filtering macro and hence will be evaluated no matter what.
func	`func()` shall be executed synchronously.

Definition at line 34 of file util.hpp.

References op_with_possible_bipc_exception().

Referenced by ipc::session::Client_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload, S_SHM_TYPE_OR_NONE, S_GRACEFUL_FINISH_REQUIRED_V >::async_connect(), op_with_possible_bipc_exception(), ipc::shm::classic::Pool_arena::Pool_arena(), and ipc::session::Session_server_impl< Session_server_t, Server_session_t >::Session_server_impl().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator!=() [1/5]

bool operator!=	(	const Process_credentials &	val1,
		const Process_credentials &	val2
	)

Checks for by-value inequality between two Process_credentials objects.

process_invoked_as() does not participate in this and is not invoked.

Parameters

val1	Value to compare.
val2	Value to compare.

Returns: Whether at least one accessor compares unequal.

Definition at line 152 of file process_credentials.cpp.

◆ operator!=() [2/5]

bool ipc::util::operator!=	(	const Shared_name &	val1,
		const Shared_name &	val2
	)

Negation of similar ==.

Parameters

val1	See `==`.
val2	See `==`.

Returns: See above.

Definition at line 378 of file shared_name.cpp.

References operator==().

Here is the call graph for this function:

◆ operator!=() [3/5]

bool ipc::util::operator!=	(	const Shared_name &	val1,
		util::String_view	val2
	)

Negation of similar ==.

Parameters

val1	See `==`.
val2	See `==`.

Returns: See above.

Definition at line 392 of file shared_name.cpp.

References operator==().

Here is the call graph for this function:

◆ operator!=() [4/5]

bool operator!=	(	Native_handle	val1,
		Native_handle	val2
	)

Negation of similar ==.

Parameters

val1	Object.
val2	Object.

Returns: See above.

Definition at line 84 of file native_handle.cpp.

◆ operator!=() [5/5]

bool ipc::util::operator!=	(	util::String_view	val1,
		const Shared_name &	val2
	)

Negation of similar ==.

Parameters

val1	See `==`.
val2	See `==`.

Returns: See above.

Definition at line 402 of file shared_name.cpp.

References operator==().

Here is the call graph for this function:

◆ operator+() [1/5]

Shared_name operator+	(	const char *	raw_src1,
		const Shared_name &	src2
	)

Returns new object equal to Shared_name(src2) with raw_src1 pre-pended to it.

Parameters

raw_src1	String to precede the appended `src2`.
src2	Object to append.

Returns: See above.

Definition at line 105 of file shared_name.cpp.

◆ operator+() [2/5]

Shared_name operator+	(	const Shared_name &	src1,
		const char *	raw_src2
	)

Returns new object equal to Shared_name(src1) += raw_src2.

Parameters

src1	Object to precede the appended `raw_src2`.
raw_src2	String to append.

Returns: See above.

Definition at line 97 of file shared_name.cpp.

Referenced by ipc::util::Shared_name::operator+().

Here is the caller graph for this function:

◆ operator+() [3/5]

Shared_name operator+	(	const Shared_name &	src1,
		const Shared_name &	src2
	)

Returns new object equal to Shared_name(src1) += src2.

Parameters

src1	Object to precede the appended `src2`.
src2	Object to append.

Returns: See above.

Definition at line 113 of file shared_name.cpp.

◆ operator+() [4/5]

template<typename Source >

Shared_name operator+	(	const Shared_name &	src1,
		const Source &	raw_src2
	)

Returns new object equal to Shared_name(src1) += raw_src2.

Template Parameters

Source See Shared_name::operator+=() similar overload.

Parameters

src1	Object to precede the appended `raw_src2`.
raw_src2	String to append.

Returns: See above.

Definition at line 708 of file shared_name.hpp.

◆ operator+() [5/5]

template<typename Source >

Shared_name operator+	(	const Source &	raw_src1,
		const Shared_name &	src2
	)

Returns new object equal to Shared_name(src2) with raw_src1 pre-pended to it.

Template Parameters

Source See Shared_name::operator+=() similar overload.

Parameters

raw_src1	String to precede the appended `src2`.
src2	Object to append.

Returns: See above.

Definition at line 716 of file shared_name.hpp.

◆ operator/() [1/5]

Shared_name operator/	(	const char *	raw_src1,
		const Shared_name &	src2
	)

Returns new object equal to Shared_name(raw_src1) /= src2.

Parameters

raw_src1	String to precede the appended separator and `src2`.
src2	Object to append after separator.

Returns: See above.

Definition at line 127 of file shared_name.cpp.

◆ operator/() [2/5]

Shared_name operator/	(	const Shared_name &	src1,
		const char *	raw_src2
	)

Returns new object equal to Shared_name(src1) /= raw_src2.

Parameters

src1	Object to precede the appended separator and `raw_src2`.
raw_src2	String to append after separator.

Returns: See above.

Definition at line 119 of file shared_name.cpp.

Referenced by ipc::util::Shared_name::operator/().

Here is the caller graph for this function:

◆ operator/() [3/5]

Shared_name operator/	(	const Shared_name &	src1,
		const Shared_name &	src2
	)

Returns new object equal to Shared_name(src1) /= src2.

Parameters

src1	Object to precede the appended separator and `src2`.
src2	Object to append after separator.

Returns: See above.

Definition at line 135 of file shared_name.cpp.

◆ operator/() [4/5]

template<typename Source >

Shared_name operator/	(	const Shared_name &	src1,
		const Source &	raw_src2
	)

Returns new object equal to Shared_name(src1) /= raw_src2.

Template Parameters

Source See Shared_name::operator/=() similar overload.

Parameters

src1	Object to precede the appended separator and `raw_src2`.
raw_src2	String to append after separator.

Returns: See above.

Definition at line 724 of file shared_name.hpp.

◆ operator/() [5/5]

template<typename Source >

Shared_name operator/	(	const Source &	raw_src1,
		const Shared_name &	src2
	)

Returns new object equal to Shared_name(raw_src1) /= src2.

Template Parameters

Source See Shared_name::operator/=() similar overload.

Parameters

raw_src1	String to precede the appended separator and `src2`.
src2	Object to append after separator.

Returns: See above.

Definition at line 732 of file shared_name.hpp.

◆ operator<() [1/2]

bool ipc::util::operator<	(	const Shared_name &	val1,
		const Shared_name &	val2
	)

Returns true if and only if val1.str() < val2.str().

Enables use of Shared_name in an std::map without jumping through any special hoops.

Parameters

val1	Object to compare.
val2	Object to compare.

Returns: See above.

Definition at line 407 of file shared_name.cpp.

References ipc::util::Shared_name::str().

Here is the call graph for this function:

◆ operator<() [2/2]

bool operator<	(	Native_handle	val1,
		Native_handle	val2
	)

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.

◆ operator<<() [1/3]

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

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.

◆ operator<<() [2/3]

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

Prints string representation of the given util::Process_credentials to the given ostream.

process_invoked_as() does not participate in this and is not invoked; you may query that information if desired manually; just remember val.process_id() must be live at the time for it to work.

Parameters

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

Returns: os.

Definition at line 157 of file process_credentials.cpp.

◆ operator<<() [3/3]

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

Prints embellished string representation of the given Shared_name to the given ostream.

Warning: This is not equivalent to writing Shared_name::str(); as of this writing it includes not just str() but also the number of characters in it as a decimal and a separator, for convenience in test/debug, to visually detect names approaching certain length limits. If you wish to output val.str(), then output... well... val.str().

Todo:: Does Shared_name operator>> and operator<< being asymmetrical get one into trouble when using Shared_name with boost.program_options (or flow::cfg which is built on top of it)? Look into it. It may be necessary to make operator<< equal to that of ostream << string after all; though the added niceties of the current << semantics may still at least be available via some explicit accessor.

Parameters

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

Returns: os.

Definition at line 353 of file shared_name.cpp.

◆ operator==() [1/5]

bool operator==	(	const Process_credentials &	val1,
		const Process_credentials &	val2
	)

Checks for by-value equality between two Process_credentials objects.

process_invoked_as() does not participate in this and is not invoked.

Parameters

val1	Value to compare.
val2	Value to compare.

Returns: Whether the accessors all compare equal.

Definition at line 146 of file process_credentials.cpp.

◆ operator==() [2/5]

bool ipc::util::operator==	(	const Shared_name &	val1,
		const Shared_name &	val2
	)

Returns true if and only if val1.str() == val2.str().

Caution: this does not execute normalize() or anything like that.

Parameters

val1	Object to compare.
val2	Object to compare.

Returns: See above.

Definition at line 373 of file shared_name.cpp.

References ipc::util::Shared_name::str().

Here is the call graph for this function:

◆ operator==() [3/5]

bool ipc::util::operator==	(	const Shared_name &	val1,
		util::String_view	val2
	)

Returns true if and only if val1.str() == string(val2).

Caution: this does not execute normalize() or anything like that.

Parameters

val1	Object to compare.
val2	String to compare.

Returns: See above.

Definition at line 383 of file shared_name.cpp.

References operator==(), and ipc::util::Shared_name::str().

Here is the call graph for this function:

◆ operator==() [4/5]

bool operator==	(	Native_handle	val1,
		Native_handle	val2
	)

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.

Referenced by ipc::util::Process_credentials::operator!=(), operator!=(), ipc::util::Native_handle::operator!=(), and operator==().

Here is the caller graph for this function:

◆ operator==() [5/5]

bool ipc::util::operator==	(	util::String_view	val1,
		const Shared_name &	val2
	)

Returns true if and only if string(val1) == val2.str().

Caution: this does not execute normalize() or anything like that.

Parameters

val1	String to compare.
val2	Object to compare.

Returns: See above.

Definition at line 397 of file shared_name.cpp.

References operator==().

Referenced by operator==().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator>>()

std::istream & operator>>	(	std::istream &	is,
		Shared_name &	val
	)

Reads Shared_name from the given istream; equivalent to reading string into Shared_name::str().

Parameters

is	Stream to read.
val	Object to which to deserialize.

Returns: is.

Definition at line 364 of file shared_name.cpp.

◆ pipe_consume()

void ipc::util::pipe_consume	(	flow::log::Logger *	logger_ptr,
		Pipe_reader *	pipe
	)

Reads a byte via the given pipe reader.

If any error occurs => undefined behavior (assert may trip). If it would-block... it will block. So: only use if your algorithm has made sure you have a byte in there.

Parameters

logger_ptr	Logger to use for logging subsequently.
pipe	The pipe.

Definition at line 96 of file util.cpp.

Referenced by ipc::session::sync_io::Session_server_adapter< Session_server >::accept_read(), ipc::transport::Posix_mq_handle::allow_impl(), ipc::transport::sync_io::Native_socket_stream_acceptor::async_accept(), ipc::transport::sync_io::Blob_stream_mq_sender_impl< Persistent_mq_handle >::async_write_q_head_payload(), ipc::util::sync_io::Timer_event_emitter::consume_timer_firing_signal(), ipc::session::sync_io::Session_adapter< Session >::on_ev_channel_open(), ipc::transport::sync_io::Blob_stream_mq_receiver_impl< Persistent_mq_handle >::read_msg(), and ipc::session::sync_io::Session_adapter< Session >::start_ops().

Here is the caller graph for this function:

◆ pipe_produce()

void ipc::util::pipe_produce	(	flow::log::Logger *	logger_ptr,
		Pipe_writer *	pipe
	)

Writes a byte to the given pipe writer.

If any error occurs => undefined behavior (assert may trip). If it would-block... it will block. So: only use if your algorithm has made sure you will never reach the pipe's capacity.

Parameters

logger_ptr	Logger to use for logging subsequently.
pipe	The pipe.

Definition at line 67 of file util.cpp.

Referenced by ipc::session::sync_io::Session_server_adapter< Session_server >::accept_write(), ipc::transport::sync_io::Native_socket_stream_acceptor::async_accept(), ipc::transport::sync_io::Blob_stream_mq_sender_impl< Persistent_mq_handle >::async_write_q_head_payload(), ipc::transport::Posix_mq_handle::interrupt_impl(), ipc::session::sync_io::Session_adapter< Session >::on_channel_func_sio(), ipc::session::sync_io::Session_adapter< Session >::on_err_func_sio(), ipc::transport::sync_io::Blob_stream_mq_receiver_impl< Persistent_mq_handle >::read_msg(), and ipc::util::sync_io::Timer_event_emitter::timer_async_wait().

Here is the caller graph for this function:

◆ process_running()

bool ipc::util::process_running ( process_id_t process_id )

Returns true if and only if the given process (by PID) is reported as running by the OS.

Caution: It may be running, but it may be a zombie; and/or it may be running now but dead shortly after this function returns. Use defensively.

Implementation: It invokes POSIX kill() with the fake zero signal; this indicates the process can be signaled and therefore exists.

Parameters

process_id The process ID of the process in question.

Returns: See above.

Definition at line 134 of file util.cpp.

Referenced by ipc::session::shm::arena_lend::jemalloc::Client_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), and ipc::session::shm::arena_lend::jemalloc::Session_server< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup().

Here is the caller graph for this function:

◆ remove_each_persistent_if()

template<typename Persistent_object , typename Filter_func >

unsigned int ipc::util::remove_each_persistent_if	(	flow::log::Logger *	logger_ptr,
		const Filter_func &	filter_func
	)

Utility that invokes Persistent_object::for_each_persistent(name_prefix_or_empty) and synchronously invokes Persistent_object::remove_persistent() on each resulting item that passes the given filter, where Persistent_object is a type that handles objects – such as SHM pools or POSIX MQs – with kernel-persistent semantics.

The number of items removed (without any error) is returned. The nature of any error(s) encountered by individual remove_persistent() calls is ignored (not returned in any way) except for logging.

This "forgiving" error emission behavior is sufficient in many cases. If you require finer control over this please use Persistent_object::for_each_persistent() and Persistent_object::remove_persistent() plus your own handling of the failure thereof in your custom handle_name_func().

Template Parameters

Persistent_object See above. It must have static methods for_each_persistent() and remove_persistent() with semantics identical to, e.g., shm::classic::Pool_arena versions of these methods. As of this writing this includes: shm::classic::Pool_arena, transport::Persistent_mq_handle (concept), transport::Posix_mq_handle, transport::Bipc_mq_handle (its impls).

Filter_func Function object with signature bool F(const Shared_name&), which should return true to delete, false to skip. For example it might simply check that name starts with a certain prefix (remove_each_persistent_with_name_prefix() uses this), or it might check whether the creating process – whose PID might be encoded in name by some convention (e.g., see ipc::session) – is alive (util::process_running()).

Parameters

logger_ptr	Logger to use for subsequently logging.
filter_func	See `Filter_func` above.

Returns: The number of successful Persistent_object::remove_persistent() calls invoked (might be zero).

Definition at line 740 of file shared_name.hpp.

◆ remove_each_persistent_with_name_prefix()

template<typename Persistent_object >

unsigned int ipc::util::remove_each_persistent_with_name_prefix	(	flow::log::Logger *	logger_ptr,
		const Shared_name &	name_prefix_or_empty
	)

Utility that invokes remove_each_persistent_if() with the filter that returns true (yes, remove) if and only if the item's name optionally matches a given Shared_name prefix.

(Optional in that supplying an .empty() prefix deletes all items.)

Template Parameters

Persistent_object See remove_each_persistent_if().

Parameters

logger_ptr	See remove_each_persistent_if().
name_prefix_or_empty	An object is removed only if its name starts with this value. This filter is skipped if the value is `.empty()`.

Returns: See remove_each_persistent_if().

Definition at line 764 of file shared_name.hpp.

References ipc::util::Shared_name::str().

Here is the call graph for this function:

◆ remove_persistent_shm_pool()

void ipc::util::remove_persistent_shm_pool	(	flow::log::Logger *	logger_ptr,
		const Shared_name &	name,
		Error_code *	err_code
	)

Equivalent to shm::classic::Pool_arena::remove_persistent().

Provided for similar reason to that described in for_each_persistent_shm_pool() doc header nearby.

Parameters

logger_ptr	See above.
name	See above.
err_code	See above.

Definition at line 119 of file util.cpp.

References ipc::util::Shared_name::native_str(), and remove_persistent_shm_pool().

Referenced by ipc::transport::Blob_stream_mq_base_impl< Persistent_mq_handle >::ensure_unique_peer(), ipc::transport::Blob_stream_mq_base_impl< Persistent_mq_handle >::remove_persistent(), ipc::shm::classic::Pool_arena::remove_persistent(), and remove_persistent_shm_pool().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_resource_permissions() [1/2]

void ipc::util::set_resource_permissions	(	flow::log::Logger *	logger_ptr,
		const fs::path &	path,
		const Permissions &	perms,
		Error_code *	err_code = `0`
	)

Utility that sets the permissions of the given resource (at the supplied file system path) to specified POSIX value.

If the resource cannot be accessed (not found, permissions...) that system Error_code shall be emitted.

Rationale

It may seem unnecessary, particularly given that it sometimes (in our internal code, but I mention it publicly for exposition purposes) placed right after the creation of the resource (file, SHM pool, POSIX MQ, shared mutex, etc.) – where the same perms is supplied to the creation-API, whichever is applicable. The reason is that those APIs tend to make the corresponding OS call (e.g., open()) which is bound by the "process umask" in POSIX/Linux; so for example if it's set to the typical 022 (octal), then it's impossible to make the resource group- or all-writable, regardless of perms. set_resource_permissions() uses a technique that bypasses the umask thing. Note that it does not make any calls to change the umask to accomplish this.

Note 1: Sometimes there is not even the creation-API argument for perms; in which case the rationale is even more straightforward.

Note 2: Sometimes there is that API... and (namely in boost.ipc at least) they actually took care to do this (what we do here) themselves (via fchmod() and such)... so we don't need to; in fact I (ygoldfel) treated it as valuable confirmation of the correctness of this maneuver.

Parameters

logger_ptr	Logger to use for logging (WARNING, on error only). Caller can themselves log further info if desired.
path	Path to resource. Symlinks are followed, and the target is the resource in question (not the symlink).
perms	See other overload.
err_code	See `flow::Error_code` docs for error reporting semantics. Error_code generated: see other overload; note that in addition file-not-found and the like are possible errors (in fact arguably the likeliest).

Definition at line 46 of file util.cpp.

References set_resource_permissions().

Referenced by ipc::transport::Posix_mq_handle::Posix_mq_handle(), ipc::session::Session_server_impl< Session_server_t, Server_session_t >::Session_server_impl(), and set_resource_permissions().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_resource_permissions() [2/2]

void ipc::util::set_resource_permissions	(	flow::log::Logger *	logger_ptr,
		Native_handle	handle,
		const Permissions &	perms,
		Error_code *	err_code = `0`
	)

Identical to the other set_resource_permissions() overload but operates on a pre-opened Native_handle (a/k/a handle, socket, file descriptor) to the resource in question.

Parameters

logger_ptr	See other overload.
handle	See above. `handle.null() == true` causes undefined behavior (assertion may trip). Closed/invalid/etc. handle will yield civilized Error_code emission.
perms	See other overload.
err_code	See `flow::Error_code` docs for error reporting semantics. Error_code generated: system error codes if permissions cannot be set (invalid descriptor, un-opened descriptor, etc.).

Definition at line 98 of file util.cpp.

References ipc::util::Native_handle::m_native_handle, ipc::util::Native_handle::null(), and set_resource_permissions().

Here is the call graph for this function:

◆ shared_resource_permissions()

Permissions ipc::util::shared_resource_permissions ( Permissions_level permissions_lvl )

Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource is in the file-system and is either accessible (read-write in terms of file system) or inaccessible.

Examples of such resources are SHM pools (e.g., shm::classic::Pool_arena), bipc MQs (transport::Bipc_mq_handle), POSIX MQs (transport::Posix_mq_handle).

Please do not confuse this setting with the read-only/read-write dichotomy potentially specified each time such a resource is opened for access (as is the case for SHM pools): the present mapping applies to a persistent protection in the file system, not at runtime at the code writer's discretion. The present permissions check is performed at opening time; the runtime writability check each time a datum is written into the resource.

Parameters

permissions_lvl The value to translate.

Returns: The result.

Definition at line 37 of file util.cpp.

References S_END_SENTINEL, and SHARED_RESOURCE_PERMISSIONS_LVL_MAP.

Referenced by ipc::session::shm::classic::Server_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::async_accept_log_in(), ipc::session::Client_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload, S_SHM_TYPE_OR_NONE, S_GRACEFUL_FINISH_REQUIRED_V >::async_connect(), ipc::session::shm::classic::Session_server< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::init_app_shm_as_needed(), ipc::session::shm::arena_lend::jemalloc::Session_server< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::init_app_shm_as_needed(), ipc::session::shm::arena_lend::jemalloc::Session_impl< Session_impl_t >::init_shm(), ipc::session::Server_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload, S_SHM_TYPE_OR_NONE, S_SHM_MAX_HNDL_SZ, S_GRACEFUL_FINISH_REQUIRED_V >::make_channel_mqs(), and ipc::session::Session_server_impl< Session_server_t, Server_session_t >::Session_server_impl().

Here is the caller graph for this function:

◆ swap()

void swap	(	Shared_name &	val1,
		Shared_name &	val2
	)

Swaps two objects.

Constant-time. Suitable for standard ADL-swap pattern using std::swap; swap(val1, val2);.

Parameters

val1	Object.
val2	Object.

Definition at line 420 of file shared_name.cpp.

Referenced by ipc::util::Native_handle::operator=().

Here is the caller graph for this function:

Variable Documentation

◆ CREATE_ONLY

const Create_only ipc::util::CREATE_ONLY

Tag value indicating an atomic create-unless-exists-else-fail operation.

Definition at line 32 of file util.cpp.

Referenced by ipc::session::shm::classic::Server_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::async_accept_log_in(), ipc::transport::Blob_stream_mq_base_impl< Persistent_mq_handle >::ensure_unique_peer(), ipc::session::shm::classic::Session_server< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::init_app_shm_as_needed(), and ipc::session::Server_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload, S_SHM_TYPE_OR_NONE, S_SHM_MAX_HNDL_SZ, S_GRACEFUL_FINISH_REQUIRED_V >::make_channel_mqs().

◆ EMPTY_STRING

const std::string ipc::util::EMPTY_STRING

A (default-cted) string. May be useful for functions returning const std::string&.

Definition at line 33 of file util.cpp.

Referenced by ipc::transport::Blob_stream_mq_receiver< Persistent_mq_handle >::nickname(), ipc::transport::Blob_stream_mq_sender< Persistent_mq_handle >::nickname(), ipc::transport::sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >::nickname(), and ipc::transport::sync_io::Blob_stream_mq_sender< Persistent_mq_handle >::nickname().

◆ IPC_KERNEL_PERSISTENT_RUN_DIR

const fs::path ipc::util::IPC_KERNEL_PERSISTENT_RUN_DIR = "/var/run"

Absolute path to the directory (without trailing separator) in the file system where kernel-persistent runtime, but not temporary, information shall be placed.

Kernel-persistent means that it'll disappear at reboot; runtime, but not temporary, means it's... not the designated temporary-data directory (informally: not /tmp). Informally: just know that it is /var/run, and that it stores things such as process-ID (PID) files.

It is a Unix path, absolute (starts with forward-slash), and lexically normal (and lacks a root-name).

Definition at line 63 of file util.cpp.

Referenced by ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cur_ns_store_absolute_path().

◆ OPEN_ONLY

const Open_only ipc::util::OPEN_ONLY

Tag value indicating an atomic open-if-exists-else-fail operation.

Definition at line 31 of file util.cpp.

Referenced by ipc::session::shm::classic::Client_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::async_connect(), ipc::transport::Bipc_mq_handle::Bipc_mq_handle(), ipc::session::Client_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload, S_SHM_TYPE_OR_NONE, S_GRACEFUL_FINISH_REQUIRED_V >::create_channel_obj(), and ipc::shm::classic::Pool_arena::Pool_arena().

◆ OPEN_OR_CREATE

const Open_or_create ipc::util::OPEN_OR_CREATE

Tag value indicating an open-if-exists-else-create operation.

Definition at line 30 of file util.cpp.

Referenced by ipc::session::Client_session_impl< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload, S_SHM_TYPE_OR_NONE, S_GRACEFUL_FINISH_REQUIRED_V >::async_connect(), and ipc::session::Session_server_impl< Session_server_t, Server_session_t >::Session_server_impl().

◆ PRODUCER_CONSUMER_RESOURCE_PERMISSIONS_LVL_MAP

const boost::array< Permissions, size_t(Permissions_level::S_END_SENTINEL)> ipc::util::PRODUCER_CONSUMER_RESOURCE_PERMISSIONS_LVL_MAP

Initial value:

= {
        Permissions(0), 
        
        Permissions(0b110000000), 
        
        Permissions(0b110100000), 
        Permissions(0b110100100) 
      }

Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource is in the file-system (e.g., a file) and is produced (and therefore always writable) by the owning (creating, updating) user; but consumed (and therefore at most readable, never writable) by potentially other processes, and therefore possibly other users (e.g., group access or unrestricted access – but only for reading either way).

For example a PID file is typically only writable by the daemon's user but may be readable or inaccessible by other users.

Definition at line 41 of file util.cpp.

Referenced by ipc::session::Session_server_impl< Session_server_t, Server_session_t >::Session_server_impl().

◆ SHARED_RESOURCE_PERMISSIONS_LVL_MAP

const boost::array< Permissions, size_t(Permissions_level::S_END_SENTINEL)> ipc::util::SHARED_RESOURCE_PERMISSIONS_LVL_MAP

Initial value:

= {
        Permissions(0), 
        Permissions(0b110000000), 
        Permissions(0b110110000), 
        Permissions(0b110110110) 
      }

Maps general Permissions_level specifier to low-level Permissions value, when the underlying resource is in the file-system and is either accessible (read-write in terms of file system) or inaccessible.

Examples of such resources are SHM pools (in Linux living in "/dev/shm") and POSIX MQs ("/dev/mqueue").

See any additional user-facing notes in shared_resource_permissions() doc header.

Definition at line 33 of file util.cpp.

Referenced by shared_resource_permissions().

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Blob_const

How to use

◆ Blob_mutable

◆ Create_only

◆ Fine_duration

◆ Fine_time_pt

◆ group_id_t

◆ Open_only

◆ Open_or_create

◆ Permissions

◆ Pipe_reader

◆ Pipe_writer

◆ process_id_t

◆ String_view

◆ Task

◆ user_id_t

Enumeration Type Documentation

◆ Permissions_level

Maintenance

Function Documentation

◆ blob_data() [1/2]

◆ blob_data() [2/2]

◆ build_conventional_non_session_based_shared_name()

◆ for_each_persistent_impl()

Errors (or lack thereof)

◆ for_each_persistent_shm_pool()

◆ hash_value() [1/2]

◆ hash_value() [2/2]

◆ op_with_possible_bipc_exception()

Background

◆ operator!=() [1/5]

◆ operator!=() [2/5]

◆ operator!=() [3/5]

◆ operator!=() [4/5]

◆ operator!=() [5/5]

◆ operator+() [1/5]

◆ operator+() [2/5]

◆ operator+() [3/5]

◆ operator+() [4/5]

◆ operator+() [5/5]

◆ operator/() [1/5]

◆ operator/() [2/5]

◆ operator/() [3/5]

◆ operator/() [4/5]

◆ operator/() [5/5]

◆ operator<() [1/2]

◆ operator<() [2/2]

◆ operator<<() [1/3]

◆ operator<<() [2/3]

◆ operator<<() [3/3]

◆ operator==() [1/5]

◆ operator==() [2/5]

◆ operator==() [3/5]

◆ operator==() [4/5]

◆ operator==() [5/5]

◆ operator>>()

◆ pipe_consume()

◆ pipe_produce()

◆ process_running()

◆ remove_each_persistent_if()

◆ remove_each_persistent_with_name_prefix()

◆ remove_persistent_shm_pool()

◆ set_resource_permissions() [1/2]

Rationale

◆ set_resource_permissions() [2/2]

◆ shared_resource_permissions()

◆ swap()

Variable Documentation

◆ CREATE_ONLY

◆ EMPTY_STRING

◆ IPC_KERNEL_PERSISTENT_RUN_DIR

◆ OPEN_ONLY