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

#include <shared_name.hpp>

Collaboration diagram for ipc::util::Shared_name:

[legend]

Public Member Functions
	Shared_name ()
	Constructs empty() name.

	Shared_name (const Shared_name &src)
	Copy-constructs from an existing Shared_name. More...

	Shared_name (Shared_name &&src_moved)
	Move-constructs from an existing Shared_name, which is made empty() if not already so. More...

template<typename Input_it >
	Shared_name (Input_it begin, Input_it end)
	Copy-constructs from a `char` range given as a pair of random-iterators; in particular `const char*`s work. More...

Shared_name &	operator= (const Shared_name &src)
	Copy-assigns from an existing Shared_name. More...

Shared_name &	operator= (Shared_name &&src_moved)
	Move-assigns from an existing Shared_name. More...

const std::string &	str () const
	Returns (sans copying) ref to immutable entire wrapped name string, suitable to pass into sys calls when naming supported shared resources assuming `absolute() == true`. More...

const char *	native_str () const
	Returns (sans copying) pointer to NUL-terminated wrapped name string, suitable to pass into sys calls when naming supported shared resources assuming `absolute() == true`. More...

size_t	size () const
	Returns `str().size()`. More...

bool	empty () const
	Returns `true` if and only if `str().empty() == true`. More...

bool	has_trailing_separator () const
	Returns `true` if and only if `!this->empty()`, and str() ends with the S_SEPARATOR character. More...

bool	absolute () const
	Returns `true` if and only if the first character is S_SEPARATOR. More...

void	clear ()
	Makes it so `empty() == true`. More...

bool	sanitized () const
	Returns `true` if and only if the contained name/fragment is sanitized according to length, legal characters, and similar. More...

bool	sanitize ()
	Best-effort attempt to turn sanitized() from `false` to `true`, unless it is already `true`; returns the final value of sanitized() indicating whether it was successful. More...

Shared_name &	operator/= (const Shared_name &src_to_append)
	Appends a folder separator followed by the given other Shared_name. More...

template<typename Source >
Shared_name &	operator/= (const Source &raw_name_to_append)
	Simply appends a folder separator followed by `raw_name_to_append` to the current value of str(). More...

Shared_name &	operator+= (const Shared_name &src_to_append)
	Appends the given other Shared_name. More...

template<typename Source >
Shared_name &	operator+= (const Source &raw_name_to_append)
	Simply appends `raw_name_to_append` to the current value of str(). More...

Static Public Member Functions
template<typename Source >
static Shared_name	ct (const Source &src)
	Copy-constructs from a `char`-sequence container such as `string` or util::String_view. More...

static Shared_name	ct (const char *src)
	Copy-constructs from a NUL-terminated `const char*` string. More...

static Shared_name	ct (std::string &&src_moved)
	Destructively move-constructs from an `std::string`, emptying that source object. More...

template<typename Integer >
static Shared_name	ct_from_int (Integer src)
	Constructs from a value of an integer type, efficiently converting to a string representation of the number in base 10. More...

Static Public Attributes
static const Shared_name	S_EMPTY
	A (default-cted) Shared_name. May be useful for functions returning `const Shared_name&`. More...

static constexpr size_t	S_MAX_LENGTH = 75
	Max value of size() such that, if str() used to name a supported shared resource, sys call safely won't barf. More...

static constexpr char	S_SEPARATOR = '_'
	Character we use, by convention, to separate conceptual folders within str(). More...

static const Shared_name	S_ROOT_MAGIC = Shared_name::ct("libipc")
	A Shared_name fragment, with no S_SEPARATOR characters inside, to be used in any Shared_name maintained by ipc itself as the leading path component. More...

static const Shared_name	S_SENTINEL = Shared_name::ct("0")
	A Shared_name fragment, with no S_SEPARATOR characters inside, that represents a path component that shall be different from any other generated string at the same path depth in the same context; and represents a sentinel. More...

static const Shared_name	S_1ST_OR_ONLY = Shared_name::ct("1")
	A Shared_name fragment, with no S_SEPARATOR characters inside, that represents a path component that (1) is not S_SENTINEL and (2) is suggested as the first or only unique ID of items at the same depth in the same context. More...

static const Shared_name	S_RESOURCE_TYPE_ID_SHM = Shared_name::ct("shm")
	Relative-folder fragment (no separators) identifying the resource type for: SHM pools. More...

static const Shared_name	S_RESOURCE_TYPE_ID_MUTEX = Shared_name::ct("mtx")
	Relative-folder fragment (no separators) identifying the resource type for: boost.interprocess named mutex. More...

Static Private Member Functions
static bool	sanitized_non_sep (char ch)
	Helper that returns `true` if and only if: `ch` is a valid character for purposes of `.sanitized() == true` but is not S_SEPARATOR. More...

Private Attributes
std::string	m_raw_name
	The name or name fragment; see str(). More...

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

Related Functions
(Note that these are not member functions.)
Shared_name	operator/ (const Shared_name &src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(src1) /= src2`. 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...

Shared_name	operator+ (const Shared_name &src1, const Shared_name &src2)
	Returns new object equal to `Shared_name(src1) += src2`. 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...

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

Detailed Description

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.

Conceptually it relates to std::string similarly to how filesystem::path does.

This is a very simple class in terms of what logic it actually adds: it encapsulates an std::string and allows for, basically, string operations like concatenation, with some syntactic sugar added for a simple folder convention. However, the design context (namely, how shared resources are named and why) is less trivial, and this doc header is a good place to get into those topics as well. Hence, we first cover practical aspects, with the architectural context referenced only as needed. Then, below that, there's an architecture discussion about naming in general.

Todo:: It would be good to constexpr-ify Shared_name to the extent possible; it might even make a dent in perf in some contexts. Internally this is annoying until C++20, where std::string itself got constexpr-ified, as we use std::string internally; best left alone until then.

Todo:: Consider adding a Shared_name_view which would be to Shared_name as String_view is to string; and that could itself be constructed from a String_view (and therefore from const char* [+ length], etc.). The main work would arguably not be the creation of that class itself but rather (1) ensuring proper implicit conversion between the main class and the new one and (2) conversion of the many Flow-IPC APIs that take a const Shared_name& that would (hopefully in essentially non-user-code-breaking ways) instead take Shared_name_view.

Construction/assignment from and conversion to strings/similar

Internally it stores an std::string.

Conversion: That string is accessible by const& via str() and similarly the NUL-terminated native_str(). Also there is an ostream<< printer; do note it does not simply print str() but rather a beautified version. (istream>> input is also provided but is identical to istream >> string.)

Construction/assignment: It comes with standard default/copy/move ctors and assignment. There is also a constructor that takes two iterators-to-char (including 2 const char*); use it for other char containers such as vector<char>. However, construction from string (including destructive move-construction), util::String_view, or NUL-terminated const char* is available exclusively in the form of static quasi-ctors ct(). Lastly: To assign please use move ctor: existing_sh_name = Shared_name::ct(src).

Rationale: C++ ADL semantics cause a ton of super-annoying problems – especially inside ipc::transport namespace itself – where compilers will auto-convert, e.g., a string to Shared_name without being asked to do so at all. For example, one sees operator << string output the string in "beautified" form, because a Shared_name is constructed implicitly and then printed via its <<. I (ygoldfel), then, took a cue from boost.asio's IP address classes which use static quasi-ctors to avoid any such issues. (The alternative was to fine-tune the ctor set a-la filesystem::path, with conversion traits and all kinds of craziness.)

Practical Shared_name matters

A shared resource in this context is some entity (such as a SHM-mapped addressable area; or a POSIX message queue) that can be opened for further access by potentially 2+ processes simultaneously. When opening (at least), the shared resource is referred to – in the associated opening sys call or similar – by a string name, and the name works equally from those 2+ processes. Shared_name stores such a string. It is also suitable for fragments of these names, including prefixes, suffixes, or middle parts. Therefore – much like boost::filesystem::path is basically a string wrapper – Shared_name is just a string wrapper. In fact the std::string it stores is accessible through str() by reference.

All standard string-like operations (generally, the +=, /=, +, and / operations) are equally performant and not any smarter than the corresponding string concatenation ops (the / variants just add a separator character). The same holds for all operations, except see the next section. In particular, all characters are allowed in any position, and there is no max length enforced. Hence, the user may assume max possible performance and zero restrictions, with the exception of:

Conventions understood/enforced by Shared_name

As noted, generally the class allows everything and does nothing smart that std::string wouldn't do. This is for flexibility and performance and is inspired by boost::filesystem::path. However, there is optional support for some simple conventions. First let's discuss those conventions:

In Flow-IPC, Shared_name is to be used for all shared resource types needed. (These are not enumerated here.) Different resource types might have different rules for (1) characters allowed; and (2) max length allowed; so that if this is violated, a creation/opening sys call (or similar) will fail with an error. Therefore, the following conventions are understood and represent the union of known system restrictions, so that sanitized() names will work for all known resource types. Also, some conventions are for human usability. In total, these conventions are understood:

Only certain characters are allowed. Namely, only alphanumerics [A-Za-z0-9] are allowed as of this writing.
There is a folder convention: We anticipate a file tree-like organization of various items; hence a folder separator character, S_SEPARATOR, is allowed also.
- A complete, usable (in a sys call or similar) name is to start with one leading S_SEPARATOR.
- We anticipate no empty "folder" names; and therefore no sequences of 2+ adjacent S_SEPARATOR chars.
Names shall not exceed a certain max length. S_MAX_LENGTH is chosen to be low enough to work for all supported resource types.

How does Shared_name actually use the knowledge of these conventions? To reiterate: normally, it does not care. The only parts of its API that do care are as follows:

absolute() will return true if and only if the first char is S_SEPARATOR. By convention, you should not pass str() to a sys call/similar, unless absolute() == true.
sanitized() will return true if and only if str() is a valid name or name fragment (no illegal characters; does not exceed S_MAX_LENGTH; no multi-separator sequences).
sanitize() will attempt to non-destructively modify (if needed) name in such a way as to make sanitized() return true.

You should call them only when you specifically need some conventions checked or enforced. Otherwise Shared_name ops will be as dumb/fast as possible.

Note: The Flow-IPC library user is unlikely to directly pass a Shared_name into a sys call or similar. Probably Flow-IPC internals will do it for the user. Therefore, the likeliest pattern for the user to encounter in public Flow-IPC APIs is: When initially naming some transport object, a constructor or factory will take a relative (absolute() == false) Shared_name prepared by the user. Within that relative fragment, the user is to use the folder conventions above (via /= or / operators perhaps) if needed. Inside Flow-IPC, the impl can then construct an absolute name by internally pre-pending stuff to the user-constructed fragment. If you have ensured the name is sanitized(), then it will not fail on account of a bad name. If you have not, then it may still not fail: sanitized() is a conservative criterion and may be too stringent for some resource types and OS calls. It is up to you to either ensure sanitized() or otherwise worry about the possibility of a bad name (illegal characters, excessive length).

Thread safety

Shared_name has the same safety under concurrency as std::string (i.e., if you intend on writing while reading/writing same *this concurrently, synchronized access is necessary to avoid corruption and other standard thread safety violations).

Architecture discussion / shared name convention synopsis

As promised, we've covered the practical aspects of Shared_name first. Now let's discuss the larger design. Note that while this does inform some of Shared_name API (which is quite simple), really the discussion has wider implications, and this doc header merely seems like a good place for it. It would've been okay to split off much of the below info into ipc::session somewhere, but... maybe that's better... but the human in me (ygoldfel) feels you'll want to know this now, here, even though for formal appropriateness maybe it should be moved. In any case here it is:

As noted before, there are N shared resource types, and Shared_name is to be used for all of them. At minimum, then:

2 names are to be equal, if and only if they refer to the same object of the same type, or they're 2 different objects but of different types.
This must be the case at each given point in time.

When designing Flow-IPC, we decided that it would be helpful for humans if we immediately made this more stringent by enforcing the following stronger requirement as well:

2 names are to be equal if and only if they are referring to objects of the same (resource) type. So then, e.g., if a SHM-area is named "X" then a POSIX queue cannot also be named "X" at the same point in time.

Further, some things are made easier if the distinctness restriction (2 distinct names <=> 2 distinct objects at each given point in time) is made more stringent by extending it to all time; resulting in:

2 names are to be equal if and only if they refer to the same object of the same type.
This must be the case over all time (not merely at each given point in time).
- In other words, if a name "X" is used for some object of some type, then it's only ever used for that object and never another (until reboot).

Note: Shared resources are assumed to be kernel-persistent, which means the slate is wiped with each system boot. Hence "all time" really means "within the relevant uptime."

Practically speaking, then, how do we enable these distinctness guarantees, in absolute names (i.e., names to be passed, usually internally by Flow-IPC, into sys calls/similar)? Firstly, the resource type for the object referred to by each absolute name should be encoded in a standard prefix inside the name; a simple distinct constant for each resource type works. There should be a handful at most of these possible values. This will guarantee non-clashing between different types of resource.

That only leaves the distinct-across-all-time requirement. However, it's outside the scope of this header to explain how that's achieved, as it involves ipc::session and other concepts and is just a large topic.

For convenience, we now summarize the resulting absolute shared name convention, as of this writing, without a full rationale and with references to other doc headers if appropriate. In order, the characters of a shared name in the Flow-IPC convention are as follows. Use session::build_conventional_shared_name() to construct a path with these semantics.

Leading S_SEPARATOR. Indicates a full (absolute) name or prefix thereof.
A certain constant magic string, S_ROOT_MAGIC, indicating ipc is operating. (E.g., if... uh... emacs likes to put stuff in, say, SHM, at a certain SHM path, hopefully it won't clash with us accidentally.)
A S_SEPARATOR.
Hard-coded resource type constant. Indicates resource type. E.g., something like "posixq" might mean a POSIX message queue. The (quite few) possible values for this are stored internally in Flow-IPC.
A S_SEPARATOR.
Session-server application name. This brief name is 1-1 with all distinct executables supported by Flow-IPC. See ipc::session for details.
A S_SEPARATOR.
Server-namespace. This uniquely identifies the server application instance across all time, for a given session-server application name. See ipc::session for how this value is computed. In the rare case where the resource applies to all server-namespaces, use special value S_SENTINEL.
A S_SEPARATOR.
What comes next depends on the scope of this particular resource.
- Relevant to a given session A-B (where A and B are processes that can converse with each other), a/k/a per-session scope:
  1. Session-client application name. Analogous to session-server application name but for the supported clients. See ipc::session for details.
  2. A S_SEPARATOR.
  3. Client-namespace. Given everything up to this point, uniquely identifies client application instance across all time (like server-namespace above, basically). See ipc::session for how it's computed.
- Relevant to no particular process pair A-B, but does apply only to a given session-client application, a/k/a per-client-app scope:
  1. Session-client application name, as just above.
  2. A S_SEPARATOR.
  3. The reserved client-namespace, S_SENTINEL, indicating no particular session-client.
- Global (not limited to any smaller scope above), a/k/a global scope. This is intended largely for internal Flow-IPC needs, as of this writing.
  1. The reserved session-client application name, S_SENTINEL, indicating no particular client application.
A S_SEPARATOR.
The rest of the name depends on the convention decided for that particular resource type and hence outside our scope here; see doc header for the relevant class corresponding to a shared resource type of interest.
- For each object, determine the scope (the 3 possibilities and resulting naming conventions are just above).
- Keep using the basic folder convention, with non-empty folder names and S_SEPARATOR as separator.
- When uniqueness is desired, the 1->2->3... technique is typically used (always remembering that such an auto-ID must be safely generated across all participating processes in system).

In rare cases a Shared_name will be used outside the ipc::session paradigm, such as for a lower-level purpose that nevertheless requires a shared-resource name (e.g., for a lower-level-use SHM pool). In that case the following shall be equal to S_SENTINEL: session-server application name; server-namespace. The components subsequent to that shall be as-if it's a global-scope resource; hence: S_SENTINEL. build_conventional_non_session_based_shared_name() shall construct such a name.

Note: camelCase: As of this writing, S_SEPARATOR is _ (because / is not available for native reasons). So, when it comes up, the convention is to use camelCase for tokens between nearby separators. Briefly: start with lower case; do not word-smoosh; each new word after word 1 is to begin with exactly 1 capital or number; an acronym is to be treated as a single word. Examples of compliant tokens: httpUrlConnectionV44Beta, tableIdent. These are bad: httpURLConnection (wrong acronym convention), HTTPURLConnection (ditto), tableident (word-smooshing).

Rationale for max length handling

As noted in the public section of this doc header: S_MAX_LENGTH is a part of sanitized() criteria; it is not enforced by Shared_name itself outside of sanitized() and sanitize(). It is up to the Shared_name user (which may be, and usually is, internal Flow-IPC code) to actually ensure sanitized() is true – or otherwise avoid system API errors on account of bad names. All we choose to do, regarding the length aspect, is choose one conservatively low so that:

At least it is no greater than the lowest inherent limit out of all the known resource types to which Shared_name applies.
Additionally, because in some cases a given public API takes a relative Shared_name and pre-pends an absolute "folder" path of known length, further leave slack to make it so that that prefix can still comfortably fit without hitting the limit from the previous bullet point.

To wit, then, current tally of relevant resource types:

POSIX message queue (man mq_overview): Linux: An internal forward-slash, included in NAME_MAX = 255 characters including NUL; so apparently: 253. (The man text could be interpreted as meaning 253, 254, 255; it is ambiguous. Experiments show it's 253.)
SHM pool (ultimately: man shm_open): Linux: Same as preceding: 253.
bipc message queue (search: boost.interprocess message_queue): It just opens a SHM pool per MQ; so same as preceding: 253.
Unix domain sockets (ultimately: man unix): Linux, abstract namespace: It's a hairy topic. sun_path[108] is the case as of this writing; minus 1 leading and trailing NUL; and there's a note some (non-Linux?) Unix domain socket implementations go as low as sun_path[92]. But in Linux: 106.

So that puts us at 106 without the "prefix slack." Applying a prefix slack of 32 characters gives us: 106 - 32 =

We round it up slightly to 75.

Definition at line 262 of file shared_name.hpp.

Constructor & Destructor Documentation

◆ Shared_name() [1/3]

ipc::util::Shared_name::Shared_name ( const Shared_name & src )

default

Copy-constructs from an existing Shared_name.

Parameters

src	Source object.

◆ Shared_name() [2/3]

ipc::util::Shared_name::Shared_name ( Shared_name && src_moved )

default

Move-constructs from an existing Shared_name, which is made empty() if not already so.

Parameters

src_moved Source object, which is potentially modified.

◆ Shared_name() [3/3]

template<typename Input_it >

ipc::util::Shared_name::Shared_name	(	Input_it	begin,
		Input_it	end
	)

explicit

Copy-constructs from a char range given as a pair of random-iterators; in particular const char*s work.

Template Parameters

Input_it An STL-compliant random iterator type. In particular const char* works.

Parameters

begin	Start of range to copy.
end	One past last element in range to copy (`begin` to copy nothing).

Definition at line 708 of file shared_name.hpp.

Member Function Documentation

◆ absolute()

bool ipc::util::Shared_name::absolute ( ) const

Returns true if and only if the first character is S_SEPARATOR.

By Flow-IPC convention, any name actually passed to a sys call in order to name a shared resource has absolute() == true. Note, however, that absolute() being true does not necessarily mean str() is the full name of a resource: it may well still be a fragment (a prefix) of some eventual name passed to a sys call. To obtain the full name one would append more stuff.

Returns: See above.

Definition at line 114 of file shared_name.cpp.

References m_raw_name, and S_SEPARATOR.

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

Here is the caller graph for this function:

◆ clear()

void ipc::util::Shared_name::clear ( )

Makes it so empty() == true.

Definition at line 119 of file shared_name.cpp.

References m_raw_name.

Referenced by ipc::transport::Posix_mq_handle::operator=().

Here is the caller graph for this function:

◆ ct() [1/3]

Shared_name ipc::util::Shared_name::ct ( const char * src )

static

Copy-constructs from a NUL-terminated const char* string.

Rationale

See class doc header for rationale as-to why this is a static ctor as opposed to a regular ctor.

Parameters

src	String to copy.

Returns: The new object.

Definition at line 49 of file shared_name.cpp.

References m_raw_name.

◆ ct() [2/3]

template<typename Source >

Shared_name ipc::util::Shared_name::ct ( const Source & src )

static

Copy-constructs from a char-sequence container such as string or util::String_view.

This overload shall be used on a non-&& arg if ct(const char*) does not apply.

Specifically the returned object's internal std::string is constructed as: std::string s(raw_name). As a result, whatever most-performant available single-arg ctor basic_string makes available is forwarded-to. (E.g., C++17 has a String_view_like ctor which is overload-resolved-to only when it most makes sense.) Hence Source must be something std::string can be constructed from in that way; e.g., vector<char> is not: use the 2-iterator ctor for that.

Rationale

See class doc header for rationale as-to why this is a static ctor as opposed to a regular ctor.

Template Parameters

Source See above.

Parameters

src	String to copy.

Returns: The new object.

Definition at line 715 of file shared_name.hpp.

References m_raw_name.

Here is the caller graph for this function:

◆ ct() [3/3]

Shared_name ipc::util::Shared_name::ct ( std::string && src_moved )

static

Destructively move-constructs from an std::string, emptying that source object.

Rationale

See class doc header for rationale as-to why this is a static ctor as opposed to a regular ctor.

Parameters

src_moved String to move (make-.empty()).

Returns: The new object.

Definition at line 56 of file shared_name.cpp.

References m_raw_name.

◆ ct_from_int()

template<typename Integer >

Shared_name ipc::util::Shared_name::ct_from_int ( Integer src )

static

Constructs from a value of an integer type, efficiently converting to a string representation of the number in base 10.

Note that a negative value yields a leading -, so the result is then not sanitized().

Template Parameters

Integer Signed or unsigned integer type of bit width 8, 16, 32, or 64. In particular bool is not supported (will not compile); char/int8_t and unsigned char/uint8_t are supported.

Parameters

src	Integer to convert.

Returns: The new object.

Definition at line 728 of file shared_name.hpp.

References m_raw_name.

Referenced by ipc::session::next_cli_namespace().

Here is the caller graph for this function:

◆ empty()

bool ipc::util::Shared_name::empty ( ) const

Returns true if and only if str().empty() == true.

Returns: See above.

Definition at line 104 of file shared_name.cpp.

References m_raw_name.

Referenced by ipc::util::build_conventional_non_session_based_shared_name(), ipc::session::build_conventional_shared_name(), ipc::session::build_conventional_shared_name_prefix(), ipc::session::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, GRACEFUL_FINISH_REQUIRED >::create_channel_obj(), has_trailing_separator(), ipc::session::shm::arena_lend::jemalloc::Session_impl< Session_impl_t >::init_shm(), ipc::session::Server_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, SHM_MAX_HNDL_SZ, GRACEFUL_FINISH_REQUIRED >::on_master_channel_open_channel_req(), and sanitize().

Here is the caller graph for this function:

◆ has_trailing_separator()

bool ipc::util::Shared_name::has_trailing_separator ( ) const

Returns true if and only if !this->empty(), and str() ends with the S_SEPARATOR character.

Returns: See above.

Definition at line 109 of file shared_name.cpp.

References empty(), m_raw_name, and S_SEPARATOR.

Here is the call graph for this function:

◆ native_str()

const char * ipc::util::Shared_name::native_str ( ) const

Returns (sans copying) pointer to NUL-terminated wrapped name string, suitable to pass into sys calls when naming supported shared resources assuming absolute() == true.

If you require an std::string (such as for some fancy boost.interprocess call), use str().

Why isn't it named `c_str()`?

It was, but capnp::StringPtr (and similar/derived classes such as capnp::Text::Reader) has a "clever" operator T() conversion operator that is enabled for all T that have .c_str(); and its implementation relies on being able to symmetrically construct T(const char*) – like std::string. We intentionally lack that. Hence renamed this away from .c_str(). This may appear like kow-towing to capnp's quirks, but actually conceivably that's a pattern people use, so let's not break it.

Returns: See above.

Definition at line 94 of file shared_name.cpp.

References m_raw_name.

Referenced by ipc::transport::Bipc_mq_handle::remove_persistent(), and ipc::util::remove_persistent_shm_pool().

Here is the caller graph for this function:

◆ operator+=() [1/2]

Shared_name & ipc::util::Shared_name::operator+= ( const Shared_name & src_to_append )

Appends the given other Shared_name.

Functionally equivalent to return *this += src_to_append.str();. If there's any reason to suspect the resulting name might be too long, execute sanitize() afterwards and ensure that returns true.

It is stylistically (and possibly for performance) better to use /= rather than manually appending a separator and then src_to_append (with this +=).

See Rationale(s) for operator/=(), as they apply here.

Parameters

src_to_append Thing to append.

Returns: *this.

Definition at line 66 of file shared_name.cpp.

References operator+=(), and str().

Referenced by operator+=(), and operator/=().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator+=() [2/2]

template<typename Source >

Shared_name & ipc::util::Shared_name::operator+= ( const Source & raw_name_to_append )

Simply appends raw_name_to_append to the current value of str().

Specifically the internal std::string is modified as: s += raw_name_to_append. As a result, whatever most-performant available (single-arg by definition) operator+= that basic_string makes available is forwarded-to. (E.g., C++17 has a String_view_like appender which is overload-resolved-to only when it most makes sense.)

If there's any reason to suspect the resulting name might be too long, execute sanitize() afterwards and ensure that returns true.

It is stylistically (and possibly for performance) better to use /= rather than manually appending a separator and then src_to_append (with this +=).

See Rationale(s) for operator/=(), as they apply here.

Template Parameters

Source See above.

Parameters

raw_name_to_append Thing to append.

Returns: *this.

Definition at line 772 of file shared_name.hpp.

References m_raw_name.

◆ operator/=() [1/2]

Shared_name & ipc::util::Shared_name::operator/= ( const Shared_name & src_to_append )

Appends a folder separator followed by the given other Shared_name.

Functionally equivalent to return *this += ((string(1, S_SEPARATOR) + src_to_append.str()));. If there's any reason to suspect this->str() already ends in S_SEPARATOR, and/or that the resulting name might be too long, execute sanitize() afterwards and ensure that returns true.

Note: The corner case, wherein &src_to_append == this, is handled properly.

It is stylistically (and possibly for performance) better to use this rather than manually appending a separator and then src_to_append (with +=).

Rationale for not doing something smarter like avoiding a double-separator due to concatenation

Basically we want things to be as fast as possible by default; and that is to make it as close to trivial string concatenation as possible. If more paranoia is required, we want the user to intentionally use sanitize() or sanitized().

Parameters

src_to_append Thing to append after appending separator.

Returns: *this.

Rationale for having this `/=` as opposed to only the version taking `Source`, or vice versa

If we had only the one taking Shared_name, then tried to use += X, where X is std::string or const char* or util::String_view, it'd have to (implicitly) construct a Shared_name first, and that is a bit slower.

If we had only the one taking Source (e.g., String_view), and user wanted to append a Shared_name, they'd have to use X.str() explicitly, losing a bit of syntactic sugar.

Same deal with += and the binary (+, /) derivations of these.

Definition at line 72 of file shared_name.cpp.

References operator/=(), and str().

Referenced by operator/=().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator/=() [2/2]

template<typename Source >

Shared_name & ipc::util::Shared_name::operator/= ( const Source & raw_name_to_append )

Simply appends a folder separator followed by raw_name_to_append to the current value of str().

Specifically the internal std::string is modified as: s += S_SEPARATOR; s += raw_name_to_append. As a result, whatever most-performant available (single-arg by definition) operator+= that basic_string makes available is forwarded-to for the 2nd +=. (E.g., C++17 has a String_view_like appender which is overload-resolved-to only when it most makes sense.)

If there's any reason to suspect this->str() already ends in S_SEPARATOR, and/or that the resulting name might be too long, execute sanitize() afterwards and ensure that returns true.

It is stylistically (and possibly for performance) better to use this rather than manually appending a separator and then src_to_append (with +=).

See Rationale(s) for the other operator/=(), as they apply here.

Caveat (handled)

If raw_name_to_append represents a range of characters that overlaps that of pre-call str() – including their being equal – this API will act functionally as-if one made a string copy of raw_name_to_append first and appended (a separator and) that copy. (This is similar to the guarantees made by string append APIs.)

Template Parameters

Source See above.

Parameters

raw_name_to_append Thing to append after appending separator.

Returns: *this.

Definition at line 792 of file shared_name.hpp.

References m_raw_name, operator+=(), and S_SEPARATOR.

Here is the call graph for this function:

◆ operator=() [1/2]

Shared_name & ipc::util::Shared_name::operator= ( const Shared_name & src )

default

Copy-assigns from an existing Shared_name.

Parameters

src	Source object.

Returns: *this.

◆ operator=() [2/2]

Shared_name & ipc::util::Shared_name::operator= ( Shared_name && src_moved )

default

Move-assigns from an existing Shared_name.

Parameters

src_moved Source object, which is potentially modified.

Returns: *this.

◆ sanitize()

bool ipc::util::Shared_name::sanitize ( )

Best-effort attempt to turn sanitized() from false to true, unless it is already true; returns the final value of sanitized() indicating whether it was successful.

If false returned, then the final value of str() will equal the initial value.

This utility should be used very judiciously and with full knowledge of what it actually does. It should not be used "just in case" or "prophylactically" but only with full knowledge of where the current value of str() might originate. For example, it might come from some user input. Another example involves, perhaps, concatenating two path fragments in such a way as to potentially yield a double-S_SEPARATOR situation: sanitize() after this would collapse the separators into just 1 separator. Yet another example is simply that if one combines two paths which don't exceed S_MAX_LENGTH, but the result might exceed it: running sanitize() and ensuring it returns true guaranteed one didn't accidentally exceed S_MAX_LENGTH.

In other words, use it when you want it to do what it, in fact, does. And that is:

Any '/' (forward-slash) character, as a special case, is transformed into S_SEPARATOR.
After any character replacements above: Any sequence of 2 or more S_SEPARATOR characters is collapsed into one S_SEPARATOR.

Things it does not do, modulo the above:

No legal or illegal character is changed (except '/' and separator collapsing).
It doesn't truncate to try to bring length to S_MAX_LENGTH or less.

However, the method's return value is still significant, in that if it is "still" false, then you know you have a real problem – yet if it's true, then it didn't do anything destructive to make it so.

Note, again, that the above replacements are "undone" if false is returned. In other words, the function won't sanitize "halfway."

Performance

There is at most one linear scan through str(), an allocation of size()d buffer, and a dealloc of ~similar.

Returns: What sanitized() would return just before returning from the present function.

Definition at line 169 of file shared_name.cpp.

References empty(), m_raw_name, S_MAX_LENGTH, S_SEPARATOR, sanitized_non_sep(), size(), ipc::util::swap(), and swap.

Here is the call graph for this function:

◆ sanitized()

bool ipc::util::Shared_name::sanitized ( ) const

Returns true if and only if the contained name/fragment is sanitized according to length, legal characters, and similar.

More precisely, a sanitized *this satisfies all of the following:

There are no illegal characters. (E.g., in particular, some characters would not be accepted when naming a SHM object in Linux.)
- In particular, only S_SEPARATOR is used as a folder separator.
There is no more than 1 instance of S_SEPARATOR character in a row.
size() does not exceed S_MAX_LENGTH.

Performance

It is linear-time, with at most one scan through str().

Returns: See above.

Definition at line 124 of file shared_name.cpp.

References m_raw_name, S_MAX_LENGTH, S_SEPARATOR, sanitized_non_sep(), and size().

Here is the call graph for this function:

◆ sanitized_non_sep()

bool ipc::util::Shared_name::sanitized_non_sep ( char ch )

staticprivate

Helper that returns true if and only if: ch is a valid character for purposes of .sanitized() == true but is not S_SEPARATOR.

Parameters

ch	Character.

Returns: See above.

Definition at line 247 of file shared_name.cpp.

Referenced by sanitize(), and sanitized().

Here is the caller graph for this function:

◆ size()

size_t ipc::util::Shared_name::size ( ) const

Returns str().size().

Returns: See above.

Definition at line 99 of file shared_name.cpp.

References m_raw_name.

Referenced by ipc::session::shm::arena_lend::jemalloc::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), ipc::transport::asio_local_stream_socket::endpoint_at_shared_name(), sanitize(), and sanitized().

Here is the caller graph for this function:

◆ str()

const std::string & ipc::util::Shared_name::str ( ) const

Returns (sans copying) ref to immutable entire wrapped name string, suitable to pass into sys calls when naming supported shared resources assuming absolute() == true.

If you require a NUL-terminated string (such as for a native call), use native_str().

Note: Returning a util::String_view seemed pointless, as one can always be constructed easily by the caller, and in any case – for the time being at least – some/many APIs that take non-C-strings will take std::string as opposed to a util::String_view.

Returns: See above.

Definition at line 89 of file shared_name.cpp.

References m_raw_name.

Referenced by ipc::session::Server_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, SHM_MAX_HNDL_SZ, GRACEFUL_FINISH_REQUIRED >::async_accept_log_in(), ipc::session::shm::arena_lend::jemalloc::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), ipc::session::shm::arena_lend::jemalloc::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), ipc::session::decompose_conventional_shared_name(), ipc::transport::asio_local_stream_socket::endpoint_at_shared_name(), hash_value(), ipc::session::Server_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, SHM_MAX_HNDL_SZ, GRACEFUL_FINISH_REQUIRED >::mdt_builder(), ipc::session::Server_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, SHM_MAX_HNDL_SZ, GRACEFUL_FINISH_REQUIRED >::on_master_channel_open_channel_req(), ipc::transport::Native_socket_stream_acceptor::on_next_peer_socket_or_error(), operator+(), operator+=(), operator/=(), operator<(), operator<<(), operator==(), ipc::util::remove_each_persistent_with_name_prefix(), and ipc::transport::Native_socket_stream_acceptor::~Native_socket_stream_acceptor().

Here is the caller graph for this function:

Friends And Related Function Documentation

◆ hash_value()

size_t hash_value ( const Shared_name & val )

Parameters

val	Object to hash.

Returns: See above.

Definition at line 334 of file shared_name.cpp.

References str().

Here is the call graph for this function:

◆ operator!=() [1/3]

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

Parameters

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

Returns: See above.

Definition at line 300 of file shared_name.cpp.

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

Here is the call graph for this function:

◆ operator!=() [2/3]

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

Parameters

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

Returns: See above.

Definition at line 314 of file shared_name.cpp.

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

Here is the call graph for this function:

◆ operator!=() [3/3]

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

Parameters

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

Returns: See above.

Definition at line 324 of file shared_name.cpp.

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

Here is the call graph for this function:

◆ operator+() [1/3]

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

Parameters

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

Returns: See above.

Definition at line 78 of file shared_name.cpp.

References str().

Here is the call graph for this function:

◆ operator+() [2/3]

template<typename Source >

Shared_name operator+	(	const Shared_name &	src1,
		const Source &	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 877 of file shared_name.hpp.

◆ operator+() [3/3]

template<typename Source >

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

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 885 of file shared_name.hpp.

References ct().

Here is the call graph for this function:

◆ operator/() [1/3]

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

Parameters

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

Returns: See above.

Definition at line 84 of file shared_name.cpp.

◆ operator/() [2/3]

template<typename Source >

Shared_name operator/	(	const Shared_name &	src1,
		const Source &	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 893 of file shared_name.hpp.

◆ operator/() [3/3]

template<typename Source >

Shared_name operator/	(	const Source &	raw_src1,
		const Shared_name &	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 901 of file shared_name.hpp.

References ct().

Here is the call graph for this function:

◆ operator<()

bool operator<	(	const Shared_name &	val1,
		const Shared_name &	val2
	)

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 329 of file shared_name.cpp.

References str().

Here is the call graph for this function:

◆ operator<<()

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

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. (An empty() name prints as null.) 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 271 of file shared_name.cpp.

References str().

Here is the call graph for this function:

◆ operator==() [1/3]

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

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 295 of file shared_name.cpp.

References str().

Here is the call graph for this function:

◆ operator==() [2/3]

bool operator==	(	const Shared_name &	val1,
		util::String_view	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 305 of file shared_name.cpp.

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

Here is the call graph for this function:

◆ operator==() [3/3]

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

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 319 of file shared_name.cpp.

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

Here is the call graph for this function:

◆ operator>>()

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

Parameters

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

Returns: is.

Definition at line 282 of file shared_name.cpp.

References ct().

Here is the call graph for this function:

◆ swap [1/2]

void swap	(	Shared_name &	val1,
		Shared_name &	val2
	)

friend

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 342 of file shared_name.cpp.

Referenced by sanitize().

◆ swap() [2/2]

void swap	(	Shared_name &	val1,
		Shared_name &	val2
	)

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

Parameters

val1	Object.
val2	Object.

Definition at line 342 of file shared_name.cpp.

Member Data Documentation

◆ m_raw_name

std::string ipc::util::Shared_name::m_raw_name

private

The name or name fragment; see str().

Todo:: Consider providing a ref-to-mutable accessor to Shared_name::m_raw_name (or just make public). There are pros and cons; the basic pro being that Shared_name is meant to be a very thin wrapper around std::string, so it might make sense to allow for in-place modification without supplying some kind of reduced subset of string API. Suggest doing this to-do if a practical desire comes about.

Definition at line 700 of file shared_name.hpp.

Referenced by absolute(), clear(), ct(), ct_from_int(), empty(), has_trailing_separator(), native_str(), operator+=(), operator/=(), sanitize(), sanitized(), size(), and str().

◆ S_1ST_OR_ONLY

const Shared_name ipc::util::Shared_name::S_1ST_OR_ONLY = Shared_name::ct("1")

static

A Shared_name fragment, with no S_SEPARATOR characters inside, that represents a path component that (1) is not S_SENTINEL and (2) is suggested as the first or only unique ID of items at the same depth in the same context.

In actual fact it equals 1; and typically (though not necessarily – other conventions may exist) generated strings shall be 1, 2, ..., of which the former is S_1ST_OR_ONLY.

So if S_SENTINEL means "not a thing" or "special thing to be treated not like a normal thing," then S_1ST_OR_ONLY means "a normal thing, of which there may be only one, and this is the first one so created."

Suggested use pattern

This is most useful when, at this path level, you currently only have reason to have one object. Then you can name it S_1ST_OR_ONLY without relying on a magic string 1. However, if in the future there is reason to add more objects at the same level, then remove the use of S_1ST_OR_ONLY and instead use a uint or atomic<uint> data member that starts at simply the numeric 1, ++ing it each time a new object is added (and converting it via Shared_name::ct(std::to_string(x)) to string). The first object will have the same name as before, compatibly, while subsequent ones will be efficiently named uniquely.

Is this cheesy and reliant on the fact that this constant is, in fact, a string conversion of the number one? Yes, but the above pattern works and is reasonably efficient. I (ygoldfel) considered making this a super-general API that keeps generating unique IDs, but it just seemed like overkill given the simplicity of the task. Converting back from Shared_name, generating a new ++ed one, then converting again – while providing a simple-enough API to ensure atomicity – seemed inferior to just letting people maintain a compatible atomic<uint>, when and if desired, and using S_1ST_OR_ONLY until then.

Definition at line 335 of file shared_name.hpp.

Referenced by ipc::session::shm::classic::Server_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::async_accept_log_in(), ipc::session::shm::classic::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::async_connect(), and ipc::session::shm::classic::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::init_app_shm_as_needed().

◆ S_EMPTY

const Shared_name ipc::util::Shared_name::S_EMPTY

static

A (default-cted) Shared_name. May be useful for functions returning const Shared_name&.

Definition at line 268 of file shared_name.hpp.

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

◆ S_MAX_LENGTH

constexpr size_t ipc::util::Shared_name::S_MAX_LENGTH = 75

staticconstexpr

Max value of size() such that, if str() used to name a supported shared resource, sys call safely won't barf.

Todo:: Shared_name::S_MAX_LENGTH currently applies to all shared resource types, but it'd be a useful feature to have different limits depending on OS/whatever limitations for particular resources types such as SHM object names versus queue names versus whatever.

See also: class doc header section: "Rationale for max length handling."

Definition at line 281 of file shared_name.hpp.

Referenced by sanitize(), and sanitized().

◆ S_RESOURCE_TYPE_ID_MUTEX

const Shared_name ipc::util::Shared_name::S_RESOURCE_TYPE_ID_MUTEX = Shared_name::ct("mtx")

static

Relative-folder fragment (no separators) identifying the resource type for: boost.interprocess named mutex.

Definition at line 341 of file shared_name.hpp.

Referenced by ipc::session::Session_base< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cur_ns_store_mutex_absolute_name(), and ipc::shm::arena_lend::detail::Shm_pool_offset_ptr_data_base::generate_pool_id().

◆ S_RESOURCE_TYPE_ID_SHM

const Shared_name ipc::util::Shared_name::S_RESOURCE_TYPE_ID_SHM = Shared_name::ct("shm")

static

Relative-folder fragment (no separators) identifying the resource type for: SHM pools.

Definition at line 338 of file shared_name.hpp.

Referenced by ipc::session::shm::classic::Server_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::async_accept_log_in(), ipc::session::shm::classic::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::async_connect(), ipc::session::shm::arena_lend::jemalloc::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), ipc::session::shm::arena_lend::jemalloc::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), ipc::shm::arena_lend::detail::Shm_pool_offset_ptr_data_base::generate_pool_id(), ipc::session::shm::classic::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::init_app_shm_as_needed(), ipc::session::shm::arena_lend::jemalloc::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::init_app_shm_as_needed(), ipc::session::shm::arena_lend::jemalloc::Session_impl< Session_impl_t >::init_shm(), and ipc::transport::Blob_stream_mq_base_impl< Persistent_mq_handle >::mq_sentinel_name().

◆ S_ROOT_MAGIC

const Shared_name ipc::util::Shared_name::S_ROOT_MAGIC = Shared_name::ct("libipc")

static

A Shared_name fragment, with no S_SEPARATOR characters inside, to be used in any Shared_name maintained by ipc itself as the leading path component.

Definition at line 298 of file shared_name.hpp.

Referenced by ipc::util::build_conventional_non_session_based_shared_name(), ipc::session::build_conventional_shared_name_prefix(), and ipc::session::decompose_conventional_shared_name().

◆ S_SENTINEL

const Shared_name ipc::util::Shared_name::S_SENTINEL = Shared_name::ct("0")

static

A Shared_name fragment, with no S_SEPARATOR characters inside, that represents a path component that shall be different from any other generated string at the same path depth in the same context; and represents a sentinel.

In actual fact it equals 0; and typically (though not necessarily – other conventions may exist) generated strings shall be 1, 2, ..., of which the former is S_1ST_OR_ONLY.

Definition at line 306 of file shared_name.hpp.

Referenced by ipc::util::build_conventional_non_session_based_shared_name(), ipc::session::build_conventional_shared_name(), ipc::session::build_conventional_shared_name_prefix(), ipc::session::Session_base< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cur_ns_store_mutex_absolute_name(), ipc::session::decompose_conventional_shared_name(), ipc::session::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, GRACEFUL_FINISH_REQUIRED >::on_master_channel_log_in_rsp(), ipc::session::Session_base< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::session_master_socket_stream_acceptor_absolute_name(), ipc::session::Session_base< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::set_cli_namespace(), and ipc::session::Session_base< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::set_srv_namespace().

◆ S_SEPARATOR

constexpr char ipc::util::Shared_name::S_SEPARATOR = '_'

staticconstexpr

Character we use, by convention, to separate conceptual folders within str().

Underscores are allowed for all applicable shared resource types. Ideally we'd use them to separate words, but 2 factors are responsible for making _ the folder separator and using camelCase to separate words between pairs of nearby underscores: 1, characters are at a premium against S_MAX_LENGTH, so we shouldn't waste them on cosmetic concerns if possible; and 2, it's unclear what other special characters (not an alphanumeric) would be suitable.

Definition at line 292 of file shared_name.hpp.

Referenced by absolute(), ipc::session::shm::arena_lend::jemalloc::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), ipc::session::shm::arena_lend::jemalloc::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cleanup(), ipc::session::decompose_conventional_shared_name(), has_trailing_separator(), operator/=(), sanitize(), sanitized(), and ipc::session::Session_server_impl< Session_server_t, Server_session_t >::Session_server_impl().

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Static Private Member Functions

Private Attributes

Friends

Related Functions

Detailed Description

Construction/assignment from and conversion to strings/similar

Practical Shared_name matters

Conventions understood/enforced by Shared_name

Thread safety

Architecture discussion / shared name convention synopsis

Rationale for max length handling

Constructor & Destructor Documentation

◆ Shared_name() [1/3]

◆ Shared_name() [2/3]

◆ Shared_name() [3/3]

Member Function Documentation

◆ absolute()

◆ clear()

◆ ct() [1/3]

Rationale

◆ ct() [2/3]

Rationale

◆ ct() [3/3]

Rationale

◆ ct_from_int()

◆ empty()

◆ has_trailing_separator()

◆ native_str()

Why isn't it named c_str()?

◆ operator+=() [1/2]

◆ operator+=() [2/2]

◆ operator/=() [1/2]

Rationale for not doing something smarter like avoiding a double-separator due to concatenation

Rationale for having this /= as opposed to only the version taking Source, or vice versa

◆ operator/=() [2/2]

Caveat (handled)

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ sanitize()

Performance

◆ sanitized()

Performance

◆ sanitized_non_sep()

◆ size()

◆ str()

Friends And Related Function Documentation

◆ hash_value()

◆ operator!=() [1/3]

◆ operator!=() [2/3]

◆ operator!=() [3/3]

◆ operator+() [1/3]

◆ operator+() [2/3]

◆ operator+() [3/3]

◆ operator/() [1/3]

◆ operator/() [2/3]

◆ operator/() [3/3]

◆ operator<()

◆ operator<<()

◆ operator==() [1/3]

◆ operator==() [2/3]

◆ operator==() [3/3]

◆ operator>>()

◆ swap [1/2]

◆ swap() [2/2]

Member Data Documentation

◆ m_raw_name

◆ S_1ST_OR_ONLY

Suggested use pattern

◆ S_EMPTY

◆ S_MAX_LENGTH

◆ S_RESOURCE_TYPE_ID_MUTEX

◆ S_RESOURCE_TYPE_ID_SHM

◆ S_ROOT_MAGIC

◆ S_SENTINEL

◆ S_SEPARATOR

Why isn't it named `c_str()`?

Rationale for having this `/=` as opposed to only the version taking `Source`, or vice versa