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...
|
|
| 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.
|
| |
| 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 char *raw_name_to_append) |
| | Similar to the overload that takes const Source&, but takes NUL-terminated string instead. 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...
|
| |
| Shared_name & | operator+= (const char *raw_name_to_append) |
| | Similar to the overload that takes const Source&, but takes NUL-terminated string instead. More...
|
| |
|
(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...
|
| |
| Shared_name | operator/ (const Shared_name &src1, const char *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 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...
|
| |
| 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...
|
| |
| Shared_name | operator+ (const Shared_name &src1, const char *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...
|
| |
| 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...
|
| |
| 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...
|
| |
| 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...
|
| |
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.
Construction/assignment from and conversion to strings/similar
Interanally 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. (ostream>> input is also provided but is identical to ostream >> 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*). However, construction from string (including destuctive move-construction), util::String_view, NUL-terminated const char*, vector<char> (etc.) 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.)
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).
| 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 get 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, except 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(). In addition, though only if actual sanitizing (by changing str()) might be necessary: an allocation, copy of str(), and deallocation may be performed. Overall, it is linear-time regardless, plus those potential alloc/dealloc ops.
- Returns
- What sanitized() would return just before returning from the present function.
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 back – 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.
