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	String_view = flow::util::String_view
	Short-hand for Flow's `String_view`.

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

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

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

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

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

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

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.

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
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 Open_or_create	OPEN_OR_CREATE
	Tag value indicating an open-if-exists-else-create operation.

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

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

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

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.

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

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

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

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

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 RWXRWXRWX 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/similar).

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.

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.

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

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

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

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

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

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

◆ operator!=() [4/5]

bool operator!=	(	Native_handle	val1,
		Native_handle	val2
	)

Negation of similar ==.

Parameters

val1	Object.
val2	Object.

Returns: See above.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

◆ 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().

◆ 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) is 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).

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

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

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

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Blob_const

How to use

◆ Blob_mutable

◆ Create_only

◆ Open_only

◆ Open_or_create

Enumeration Type Documentation

◆ Permissions_level

Function Documentation

◆ blob_data() [1/2]

◆ blob_data() [2/2]

◆ hash_value() [1/2]

◆ hash_value() [2/2]

◆ 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>>()

◆ process_running()

◆ remove_each_persistent_if()

◆ remove_each_persistent_with_name_prefix()

◆ set_resource_permissions() [1/2]

Rationale

◆ set_resource_permissions() [2/2]

◆ shared_resource_permissions()

◆ swap()