|
Flow-IPC 3.0.0
Flow-IPC project: Full implementation reference.
|
Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifically. More...
Namespaces | |
| namespace | error |
| Analogous to ipc::transport::error but applies to the sub-namespace ipc::transport::struc – errors having to do with structured messaging. | |
| namespace | shm |
| Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::struc proper – most notably the concepts ipc::transport::struc::Struct_builder and ipc::transport::struc::Struct_reader – and items related to them. | |
| namespace | stat |
| Stats-related sub-namespace, for ADL segregation and general organization. | |
| namespace | sync_io |
sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport::struc. | |
Classes | |
| class | Capped_sz_capnp_message_builder |
Simple utility: a capnp MessageBuilder operating over a single, contiguous, user-supplied area in virtual memory. More... | |
| class | Capped_sz_capnp_message_reader |
Simple utility: a capnp MessageReader operating over a single, contiguous, user-supplied area in virtual memory. More... | |
| class | Channel |
| Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel over which unstructured messages and optionally native handles can be transported), this template is the central pillar of the ipc::transport::struc (structured layer), capable of communicating structured capnp-schema-based messages (and native handles). More... | |
| class | Channel_base |
Channel base that contains non-parameterized items such as tag types and constants. More... | |
| class | Heap_fixed_builder |
~Simplest possible impl of Struct_builder concept that represents the capnp payload directly in heap memory (outer serialization only), with a segment-allocation strategy similar to capnp::MallocMessageBuilder. More... | |
| class | Heap_fixed_builder_capnp_message_builder |
A capnp::MessageBuilder used by Heap_fixed_builder: similar to a capnp::MallocMessageBuilder (albeit with somewhat different accounting/knobs) and with framing/header space around the allocated segment(s). More... | |
| class | Heap_reader |
Implements Struct_reader concept by straightforwardly interpreting a serialization by Heap_fixed_builder or any other builder that produces segments directly readable via SegmentArrayMessageReader. More... | |
| class | Msg_in |
| A structured in-message instance suitable as received and emittable (to user) by struc::Channel. More... | |
| struct | Msg_in_impl |
This is the friend facade of Msg_in that exposes private APIs hidden from public user by providing public access to them; this is used internally by struc::sync_io::Channel at least. More... | |
| class | Msg_out |
| A structured out-message suitable to be sent via struc::Channel::send() (et al). More... | |
| struct | Msg_out_impl |
This is the friend facade of Msg_out that exposes private APIs hidden from public user by providing public access to them; this is used internally by struc::sync_io::Channel at least. More... | |
| struct | Null_session |
| Value for Struct_builder::Session when no extra information is needed when serializing Struct_builder for subsequent sending to another process. More... | |
| struct | Ostreamable_capnp_brief |
Proxy object referring to a capnp Reader for straightforward output via overloaded ostream<<: one-line/potentially-truncated form. More... | |
| struct | Ostreamable_capnp_full |
Proxy object referring to a capnp Reader for straightforward output via overloaded ostream<<: multi-line/pretty-printed/indented/full-length form. More... | |
| struct | Split_segment |
| Simple structure describing how a pre-split single segment was turned into 2+ post-split component sub-segments. More... | |
| class | Struct_builder |
A documentation-only concept defining the behavior of an object capable of zero-copy-serializing, similar to capnp::MessageBuilder but geared to transmission over pipe-like IPC transports. More... | |
| class | Struct_reader |
A documentation-only concept that is, conceptually, roughly what capnp::MessageReader is to capnp::MessageBuilder, to be used on an in-message serialized by a counterpart Struct_builder, having been transmitted over an IPC transmitter of blobs. More... | |
Typedefs | |
| template<typename Channel_obj , typename Msg_body_t > | |
| using | Channel_via_heap = Channel< Channel_obj, Msg_body_t, Heap_fixed_builder::Config, Heap_reader::Config > |
| Convenience alias: Use this when constructing a struc::Channel with tag Channel_base::S_SERIALIZE_VIA_HEAP. More... | |
| using | Session_token = boost::uuids::uuid |
| A type used by struc::Channel for internal safety/security/auth needs. More... | |
| using | Segment_ptrs = std::vector< flow::util::Blob_sans_log_context * > |
Sequence of 1+ segment descriptions, each representing a live writable segment (of a capnp serialization of a capnp-struct) and optional header/prefix area immediately preceding it. More... | |
| using | Segment_bufs = std::vector< util::Blob_const > |
Simpler cousin of Segment_ptrs, this represents the IPC-transmissible representation of a capnp serialization of a capnp-struct including any framing header(s), expressed as simply a sequence of N read-only views, each containing a pointer to header-if-any-followed-by-serialization-segment and the size in bytes thereof. More... | |
| using | Split_segments = std::vector< Split_segment > |
| A simple data structure describing the segments (if any) in a Segment_bufs (or similar) structure which had to be split (presumably due to size constraints); by following the indices/sizes into a post-split Segment_bufs one can join the appropriate elements so as to obtain the original pre-split segments. More... | |
| using | Segment_blob_in = flow::util::Blob_sans_log_context |
| Short-hand for a high-performance blob structure that represents an IPC-incoming (sub-)segment 1+ of which make up the outer serialization of a given Msg_in. More... | |
| using | msg_id_t = uint64_t |
Message ID uniquely identifying outgoing message (Msg_out, among all other Msg_outs), per channel; and similarly incoming message (Msg_in, among Msg_ins), per channel. More... | |
| using | Capnp_msg_builder_interface = ::capnp::MessageBuilder |
| Alias for capnp's MessageBuilder interface. Rationale: as part of our API, we use our identifier style. More... | |
| using | Capnp_msg_reader_interface = ::capnp::MessageReader |
| Alias for capnp's MessageReader interface. Rationale: as part of our API, we use our identifier style. More... | |
Functions | |
| bool | load_mdt (Capped_sz_capnp_message_builder *builder, schema::detail::StructuredMessage::InternalMessageBody::Builder *internal_msg_builder_or_null, Error_code *err_code, const Session_token &session_token, msg_id_t originating_msg_id_or_none, msg_id_t id_or_none=0, size_t n_serialization_segments_or_none=0, const Split_segments *split_segs=nullptr) |
Given user- or internal-message-describing metadata values as arguments, loads (via the provided capnp::MessageBuilder) a schema::detail::StructuredMessage capnp-struct so as to contain those values. More... | |
| std::ostream & | operator<< (std::ostream &os, const Heap_fixed_builder &val) |
Prints string representation of the given Heap_fixed_builder to the given ostream. More... | |
| std::ostream & | operator<< (std::ostream &os, const Heap_reader &val) |
Prints string representation of the given Heap_reader to the given ostream. More... | |
| template<typename Body_t , typename Struct_builder_t > | |
| std::ostream & | operator<< (std::ostream &os, const Msg_out< Body_t, Struct_builder_t > &val) |
Prints string representation of the given Msg_out to the given ostream. More... | |
| template<typename Body_t , typename Reader_config_t > | |
| std::ostream & | operator<< (std::ostream &os, const Msg_in< Body_t, Reader_config_t > &val) |
Prints string representation of the given Msg_in to the given ostream. More... | |
| template<typename Capnp_reader > | |
| Ostreamable_capnp_brief< Capnp_reader > | ostreamable_capnp_brief (const Capnp_reader &capnp_reader) |
Convenience function that returns an object passable to ostream<< to print a one-line/potentially-truncated representation to that stream, given an arbitrary capnp Reader. More... | |
| template<typename Capnp_reader > | |
| Ostreamable_capnp_full< Capnp_reader > | ostreamable_capnp_full (const Capnp_reader &capnp_reader) |
Convenience function that returns an object passable to ostream<< to print a multi-line/pretty-printed/indented/full-length representation to that stream, given an arbitrary capnp Reader. More... | |
| template<typename Capnp_reader > | |
| std::ostream & | operator<< (std::ostream &os, const Ostreamable_capnp_brief< Capnp_reader > &val) |
Prints string representation (one-line/potentially-truncated form) of the given capnp Reader, via proxy object, to the given ostream. More... | |
| template<typename Capnp_reader > | |
| std::ostream & | operator<< (std::ostream &os, const Ostreamable_capnp_full< Capnp_reader > &val) |
Prints string representation (multi-line/pretty-printed/indented/full-length form) of the given capnp Reader, via proxy object, to the given ostream. More... | |
| template<typename Owned_channel_t , typename Msg_body_t , typename Builder_config_t , typename Reader_config_t > | |
| std::ostream & | operator<< (std::ostream &os, const Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t > &val) |
Prints string representation of the given struc::Channel to the given ostream. More... | |
Variables | |
| const Session_token | NULL_SESSION_TOKEN = boost::uuids::nil_uuid() |
A value for which .is_nil() is true. More... | |
| const Null_session | NULL_SESSION |
| The only necessary value of empty-type Null_session. More... | |
| static constexpr size_t | BUILDER_CONFIG_FRAME_PREFIX_SZ_VIA_STRUC_CHANNEL = 128 |
struc::Channel (and struc::sync_io::Channel) requires, for internal purposes, that any Msg_out transmitted over it was provided with a Struct_builder::Config that has m_frame_prefix_sz member set to this value (or larger if desired for some purpose). More... | |
Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifically.
See ipc::transport doc header. As that notes, the big daddy here is struc::Channel.
Be aware of sub-namespace ipc::transport::struc::shm which concerns itself with end-to-end-zero-copyable messages leveraging in-SHM storage. Normally there's no need for the user to know or worry about it, but for advanced applications, particularly extensions and customizations, one might delve into this area of the code. Otherwise it'll be used silently as important glue between various systems. Your journey would likely start with the struc::Builder concept doc header which would then lead you to struc::shm::Builder impl. That might lead you to specific SHM-providers like ipc::shm::classic.
| using ipc::transport::struc::Capnp_msg_builder_interface = typedef ::capnp::MessageBuilder |
Alias for capnp's MessageBuilder interface. Rationale: as part of our API, we use our identifier style.
Definition at line 218 of file struc_fwd.hpp.
| using ipc::transport::struc::Capnp_msg_reader_interface = typedef ::capnp::MessageReader |
Alias for capnp's MessageReader interface. Rationale: as part of our API, we use our identifier style.
Definition at line 221 of file struc_fwd.hpp.
| using ipc::transport::struc::Channel_via_heap = typedef Channel<Channel_obj, Msg_body_t, Heap_fixed_builder::Config, Heap_reader::Config> |
Convenience alias: Use this when constructing a struc::Channel with tag Channel_base::S_SERIALIZE_VIA_HEAP.
See Channel_base::Serialize_via_heap doc header for when/how to use.
Tip: Sync_io_obj member alias will get you the sync_io-pattern counterpart.
Unable to put it in ..._fwd.hpp, because it relies on nested class inside incomplete type.
Definition at line 483 of file heap_serializer.hpp.
| using ipc::transport::struc::msg_id_t = typedef uint64_t |
Message ID uniquely identifying outgoing message (Msg_out, among all other Msg_outs), per channel; and similarly incoming message (Msg_in, among Msg_ins), per channel.
0 is a sentinel value and not a valid user message ID. A message ID pertains to a sent or received instance of a user-created Msg_out (and its in-message counterpart Msg_in). A given Msg_out can be sent 2+ times through a given struc::Channel and even a different struc::Channel; a different message ID will pertain to each of those times for a given struc::Channel. Therefore there is no msg_id_t inside a user Msg_out.
This type is in the public API, as the message ID is made available in certain contexts for:
It can also be used as a sequence number and is therefore assigned from sequence 1, 2, ... (0 is sentinel).
Needs to be big enough to where there's no chance it overflows in a given channel for a given direction. Assume 1 billion messages per second, or about 2^30 msg/s. That would take 2^(64-30), or 2^34, seconds, or over 500 years, to overflow. So this should be fine. Moreover overflow is fine in that case, in practice, if this is used only as a unique ID; it would however in theory present problems if used as a sequence number.
Definition at line 215 of file struc_fwd.hpp.
| using ipc::transport::struc::Segment_blob_in = typedef flow::util::Blob_sans_log_context |
Short-hand for a high-performance blob structure that represents an IPC-incoming (sub-)segment 1+ of which make up the outer serialization of a given Msg_in.
Its exact semantics are context-dependent, so it's best to read the API or context to determine such details.
Definition at line 192 of file struc_fwd.hpp.
| using ipc::transport::struc::Segment_bufs = typedef std::vector<util::Blob_const> |
Simpler cousin of Segment_ptrs, this represents the IPC-transmissible representation of a capnp serialization of a capnp-struct including any framing header(s), expressed as simply a sequence of N read-only views, each containing a pointer to header-if-any-followed-by-serialization-segment and the size in bytes thereof.
Note that while Segment_ptrs contains info on header size, this Segment_bufs does not: So to properly interpret the given Blob_const element, one must know the size of the header therein (if any; by convention we can say that no header => header size is 0 => segment = entire Blob_const).
Definition at line 171 of file struc_fwd.hpp.
| using ipc::transport::struc::Segment_ptrs = typedef std::vector<flow::util::Blob_sans_log_context*> |
Sequence of 1+ segment descriptions, each representing a live writable segment (of a capnp serialization of a capnp-struct) and optional header/prefix area immediately preceding it.
As of this writing this is specifically 1+ Basic_blob pointers to blobs that directly represent those segments+header(s) which must stay alive while these pointers may be dereferenced. In each Basic_blob [begin(), end()) is the serialization segment itself; and space before begin() (of size start()) may be reserved for framing prefix/header to preserve zero-copy when transmitting such serializations over an IPC "wire." (Area after end() up to capacity() could represent a framing postfix, though as of this writing we assume only a header might exist, for simplicity. As long as possible we shall avoid adding a postfix into the design.)
Why represent the segment+header as Basic_blob specifically? Answer: The relevant serialization engine(s) could internally represent data structures (namely segments and frame-prefix and such) however they want, and indeed by choosing Basic_blob* here essentially we force that impl to be specifically that. That is a very reasonable structure (and less-feature-filled, slightly-higher-performing than the derivative Blob), but why force it? Indeed, as regards a public API, something merely describing locations and sizes inside the data structure of choice would be stylistically more direct and therefore more flexible/better. To wit Segment_bufs (sequence of pointer + size pairs essentially) is almost such a thing; just it's not quite enough, because it does not directly/intuitively represent the header/prefix areas that might precede segments (but instead merely the segments themselves). So we choose Basic_blob* simply because it is (1) a decent choice for all impls in practice and (2) sufficiently-well describes both segments and frame headers nearby. It is slightly inflexible but acceptable overall.
Segment_ptrs element type would ideally be a view into Blob-or-similar instead of actual Basic_blob*, to decouple impl from API more cleanly. One approach might be to develop a flow::util class/template, a peer of the flow::util::Blob hierarchy, that specifically represents a view into a Blob-type-thing (perhaps 1 variant for mutable, 1 variant for immutable), perhaps analogously to how span<uint8_t> + span<const uint8_t> is each a view into vector<uint8_t> (minus the latter's capacity). It would therefore store a pointer, a size, a capacity, and a start-index – representing a main buffer (size() in size), N-byte header/prefix (N = start()), and M-byte postfix (M = capacity() - start() - size()). (A more economical buffer+header version – directly applicable here – might store all of those minus the capacity, meaning there is no postfix area.) Possible names might be Blob_view_const (read-only view into buffer plus header plus postfix), Blob_view_mutable (same plus writable access), Prefixed_byte_span_const (Blob_view_const minus postfix area), Prefixed_byte_span_mutable (Blob_view_mutable minus postfix area). Segment_ptrs would likely be vector<Prefixed_byte_span_mutable>. Definition at line 160 of file struc_fwd.hpp.
| using ipc::transport::struc::Session_token = typedef boost::uuids::uuid |
A type used by struc::Channel for internal safety/security/auth needs.
See in particular struc::Channel constructors, both the regular-channel one and the session-master-channel one. That said: The user of ipc::transport (aided by ipc::session) structured layer shall generally be unconcerned with this, in practice, as ipc::session machinery will take care of:
struc::Channels as requested by the user (the preceding bullet's token shall be passed to each new struc::Channel and expected internally in all messages).However, if one plans to create a struc::Channel directly (as ipc::session does), then one must have some limited understanding of this guy's existence (if not the internal details).
As you can see: internally it is a UUID (RFC 4122 Universally Unique IDentifier) which is 128 bits (16 bytes) in size. It's also a POD (Plain Old Data object), meaning it's ctor-free (direct-initialized) and can be memcpy()d around and such. See boost.uuid docs (which are simple).
A session master channel struc::Channel, operating in server mode during the log-in phase, will (as of this writing anyway) generate this using the boost.uuid random UUID generator. From that point on all channels spawned through that guy (by ipc::session) will be cted with that token value; and all messages both in those channels and the original master channel (after the log-in message exchange) will send this value and ensure any in-message has that value (or immediately hose the channel – auth failure). This is a safety (not really security, due to the lack of token invalidation at least) measure. It will reduce chances that "wires get crossed," and a message goes into the wrong channel somehow.
That's how it's used. Is the random-generator method of UUID generation acceptable for this use?
A bit of research (starting in the RFC perhaps; or Wikipedia) shows that collisions are so cosmically rare as to make it, quite officially, a non-concern. Even if one does not accept that, however, suppose a collision does occur: two channels happen to generate the same UUID on the same machine around the same time. This (essentially impossible) scenario would not cause either channel to break; it would only allow (in theory) a token check to succeed where it shouldn't, if the fabled wires-crossed scenario occurred. This is an acceptable level of risk.
Conversely, perhaps using UUIDs for this is overkill. 128 bits isn't heavy, but perhaps something smaller – maybe even much smaller, like 32 bits or even 16 – would improve perf without really reducing effectiveness given the above rationale. Indeed that's worth considering but only in the phase where perf optimization is the explicit goal. Until then (if that even happens) the ability to use the nice boost.uuid library instead of rolling our own jankier/smaller UUID-like thing (or whatever) is well worth the alleged perf cost.
Definition at line 121 of file struc_fwd.hpp.
| using ipc::transport::struc::Split_segments = typedef std::vector<Split_segment> |
A simple data structure describing the segments (if any) in a Segment_bufs (or similar) structure which had to be split (presumably due to size constraints); by following the indices/sizes into a post-split Segment_bufs one can join the appropriate elements so as to obtain the original pre-split segments.
The order of Split_segments is strictly from left to right. A reasonable join algorithm, therefore, would iterate over a Split_segments in reverse order; for each Split_segment join the 2+ segments in the post-split Segment_bufs (or similar) described therein, in-place. By doing this in reverse order, handling Split_segment A before B will not invalidate the start-index member in B.
By convention Split_segments shall include a Split_segment only if a segment actually needed to be split.
Definition at line 185 of file struc_fwd.hpp.
| bool ipc::transport::struc::load_mdt | ( | Capped_sz_capnp_message_builder * | builder, |
| schema::detail::StructuredMessage::InternalMessageBody::Builder * | internal_msg_builder_or_null, | ||
| Error_code * | err_code, | ||
| const Session_token & | session_token, | ||
| msg_id_t | originating_msg_id_or_none, | ||
| msg_id_t | id_or_none = 0, |
||
| size_t | n_serialization_segments_or_none = 0, |
||
| const Split_segments * | split_segs = nullptr |
||
| ) |
Given user- or internal-message-describing metadata values as arguments, loads (via the provided capnp::MessageBuilder) a schema::detail::StructuredMessage capnp-struct so as to contain those values.
The resulting MessageBuilder a/k/a Capnp_msg_builder_interface can then be serialized as an mdt header for an out-message.
The out-arg *builder may be reused for performance; meaning if it encoded mdt for out-message X earlier, it can be reused to encode mdt for out-message Y now with higher perf than if a fresh *builder had to be created. There are however the following limitations.
internal_msg_builder_or_null != nullptr, and id_or_none == 0), then *builder must be fresh. Else behavior is undefined.*builder is previously-load_mdt()ed:*builder must have been used to also load a user message's MDT. Else behavior is undefined.true indicating success.false indicating reuse failure. You should in that case try again, passing-in a fresh *builder. We'll return true that time.In other words:
*builder is fresh, all is cool; we'll return true.*builder is being reused:*builder must have been load_mdt()ed for the same purpose (user message, not internal message).true.false. Try again with fresh *builder.The above ignores the possibility of fatal error, meaning an input such that for internal reasons load_mdt() cannot work, regardless of *builder freshness. So far we've described these:
false returned: no fatal error; try with fresh *builder as explained.true returned, and *err_code is falsy post-call: no fatal error; all good as explained.That leaves this one:
true returned, and *err_code is truthy post-call: fatal error; recommend emitting to user.id_or_none == 0 (for internal messages). Only user messages have enough degrees of freedom as to overload the mdt conventions we've established internally.| builder | A MessageBuilder. If id_or_none == 0, it must be fresh (not previously load_mdt()ed). Else it may be fresh or previously load_mdt()ed; in the latter case id_or_none != 0 had to have been the case as well. / If we return true, *builder will have been loaded with a filled-out schema::detail::StructuredMessage. |
| internal_msg_builder_or_null | Must be null if and only if id_or_none != 0, indicating we're loading a user message's mdt. Else we're loading an internal message. In that case the post-condition is: we return true (always succeed); and *internal_msg_builder_or_null is a capnp-Builder for the schema::detail::StructuredMessage::InternalMessageBody node inside *builder. It is the return value of .initInternalMessageBody(), but that node's insides have not been filled further. The caller should use the Builder to set the particulars of the internal message per schema (see structured_msg.capnp). |
| err_code | To set, if and only if returning true (see above). If null behavior is undefined (assertion may trip). As of this writing generated codes: error::Code::S_SERIALIZE_FAILED_SPLIT_ENCODING_TOO_BIG (a Split_segment record's field's value does not fit the chosen capnp-encoding type's bit-width); error::Code::S_SERIALIZE_FAILED_SPLIT_SEGS_TOO_MANY (the mdt in total, due to its variable-length parts – in practice the *split_segs-encoding list as of this writing – does not fit *builder's fixed-size area; a 2nd segment would be needed => this error). |
| session_token | The token to load into *builder. |
| originating_msg_id_or_none | Message ID of the in-message to which this one responds or which this one otherwise references; or 0 if none. |
| id_or_none | Message ID of the user message whose mdt we're loading; or 0 to indicate we're loading an internal message. |
| n_serialization_segments_or_none | Must be 0 if and only if id_or_none == 0, indicating we're loading an internal message. Else we're loading a user message. In that case this is the number of (sub-)segments composing the user message's payload (this is 1 or higher). Some of these (sub-)segments may need to be re-joined by the receiver before being used as actual capnp-serialization segments; in which case this info is in split_segs. |
| split_segs | Must be null and is otherwise ignored if id_or_none == 0 (internal message case). Else it's a user message's mdt; in which case: If split_segs is null, then no splitting of segments was needed, hence no re-joining is needed on the opposing side; otherwise it is a list (by convention of size at least 1) describing the split structure. See Split_segments doc header for details. |
true means success, false means retry sans reuse. Definition at line 43 of file msg_impl.cpp.
References ipc::transport::struc::error::S_INVALID_ARGUMENT, ipc::transport::struc::error::S_SERIALIZE_FAILED_SPLIT_ENCODING_TOO_BIG, and ipc::transport::struc::error::S_SERIALIZE_FAILED_SPLIT_SEGS_TOO_MANY.
Referenced by ipc::transport::struc::Msg_out< Body_t, Builder_t >::emit_serialization(), and ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::rcv_struct_inform_of_unexpected_response().
| std::ostream & operator<< | ( | std::ostream & | os, |
| const Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t > & | val | ||
| ) |
Prints string representation of the given struc::Channel to the given ostream.
| os | Stream to which to write. |
| val | Object to serialize. |
os. | std::ostream & operator<< | ( | std::ostream & | os, |
| const Heap_fixed_builder & | val | ||
| ) |
Prints string representation of the given Heap_fixed_builder to the given ostream.
| os | Stream to which to write. |
| val | Object to serialize. |
os. Definition at line 263 of file heap_serializer.cpp.
| std::ostream & operator<< | ( | std::ostream & | os, |
| const Heap_reader & | val | ||
| ) |
Prints string representation of the given Heap_reader to the given ostream.
| os | Stream to which to write. |
| val | Object to serialize. |
os. Definition at line 356 of file heap_serializer.cpp.
| std::ostream & operator<< | ( | std::ostream & | os, |
| const Msg_in< Body_t, Reader_config_t > & | val | ||
| ) |
| std::ostream & operator<< | ( | std::ostream & | os, |
| const Msg_out< Body_t, Struct_builder_t > & | val | ||
| ) |
Prints string representation of the given Msg_out to the given ostream.
Namely it prints via Msg_out::to_ostream(); be sure to read perf notes on that!
| os | Stream to which to write. |
| val | Object to serialize. |
os. | std::ostream & ipc::transport::struc::operator<< | ( | std::ostream & | os, |
| const Ostreamable_capnp_brief< Capnp_reader > & | val | ||
| ) |
Prints string representation (one-line/potentially-truncated form) of the given capnp Reader, via proxy object, to the given ostream.
Reader capnp_reader (or builder.asReader()) in this call to make use of this output operator conveniently.| os | Stream to which to write. |
| val | Object to serialize. |
os. Definition at line 83 of file util.hpp.
References ipc::transport::struc::Ostreamable_capnp_brief< Capnp_reader >::m_capnp_reader.
| std::ostream & ipc::transport::struc::operator<< | ( | std::ostream & | os, |
| const Ostreamable_capnp_full< Capnp_reader > & | val | ||
| ) |
Prints string representation (multi-line/pretty-printed/indented/full-length form) of the given capnp Reader, via proxy object, to the given ostream.
Reader capnp_reader (or builder.asReader()) in this call to make use of this output operator conveniently.| os | Stream to which to write. |
| val | Object to serialize. |
os. Definition at line 101 of file util.hpp.
References ipc::transport::struc::Ostreamable_capnp_full< Capnp_reader >::m_capnp_reader.
| Ostreamable_capnp_brief< Capnp_reader > ipc::transport::struc::ostreamable_capnp_brief | ( | const Capnp_reader & | capnp_reader | ) |
Convenience function that returns an object passable to ostream<< to print a one-line/potentially-truncated representation to that stream, given an arbitrary capnp Reader.
| capnp_reader | The Reader to presumably print. Tip: if you have a Builder builder to print then pass builder.asReader() here. |
Definition at line 71 of file util.hpp.
Referenced by ipc::transport::struc::shm::rpc::Session_vat_network< Shm_lender_borrower_t, Shm_arena_t >::Rpc_msg_in_impl::Rpc_msg_in_impl(), ipc::transport::struc::shm::rpc::Session_vat_network< Shm_lender_borrower_t, Shm_arena_t >::Rpc_msg_out_impl::send(), ipc::transport::struc::Msg_out< Body_t, Builder_t >::to_ostream(), and ipc::transport::struc::Msg_in< Body_t, Reader_config_t >::to_ostream().
| Ostreamable_capnp_full< Capnp_reader > ipc::transport::struc::ostreamable_capnp_full | ( | const Capnp_reader & | capnp_reader | ) |
Convenience function that returns an object passable to ostream<< to print a multi-line/pretty-printed/indented/full-length representation to that stream, given an arbitrary capnp Reader.
| capnp_reader | The Reader to presumably print. Tip: if you have a Builder builder to print then pass builder.asReader() here. |
Definition at line 77 of file util.hpp.
Referenced by ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::rcv_on_async_read_channel_header(), ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::rcv_on_async_read_lead_msg(), ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::rcv_on_async_read_proto_neg_msg(), ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::rcv_struct_inform_of_unexpected_response(), ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::rcv_struct_new_msg_in(), ipc::transport::struc::shm::rpc::Session_vat_network< Shm_lender_borrower_t, Shm_arena_t >::Rpc_msg_in_impl::Rpc_msg_in_impl(), ipc::transport::struc::shm::rpc::Session_vat_network< Shm_lender_borrower_t, Shm_arena_t >::Rpc_msg_out_impl::send(), ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::send_impl(), and ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::send_init_msgs().
|
staticconstexpr |
struc::Channel (and struc::sync_io::Channel) requires, for internal purposes, that any Msg_out transmitted over it was provided with a Struct_builder::Config that has m_frame_prefix_sz member set to this value (or larger if desired for some purpose).
As of this writing that includes Heap_fixed_builder::Config::m_frame_prefix_sz (for heap-backed messages) and shm::Builder::Config::m_frame_prefix_sz (for SHM-backed ones).
In typical usage patterns one need not assemble a Struct_builder::Config explicitly, but nothing forbids it, hence it seemed prudent to expose this publicly.
Note that Struct_builders and hence their Configs (formally speaking) may be used independently of struc::Channel, so it is conceivable to not need this value set (e.g., 0 would be quite conceivable). (In fact internally Flow-IPC might use these guys in various capacities and may well set .m_frame_prefix_sz = 0 in some contexts.) That is to say, m_frame_prefix_sz should not simply be removed from our APIs and replaced by a constant all-over.
Definition at line 247 of file struc_fwd.hpp.
Referenced by ipc::transport::struc::Msg_in< Body_t, Reader_config_t >::add_serialization_segment(), ipc::session::shm::classic::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::app_shm_builder_config(), ipc::session::shm::arena_lend::jemalloc::Session_server< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::app_shm_builder_config(), ipc::session::shm::arena_lend::jemalloc::Server_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload >::app_shm_builder_config(), ipc::transport::struc::Msg_in< Body_t, Reader_config_t >::deserialize_mdt(), ipc::transport::struc::Msg_out< Body_t, Builder_t >::emit_serialization(), ipc::transport::struc::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::heap_fixed_builder_config(), ipc::session::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, GRACEFUL_FINISH_REQUIRED >::mdt_builder(), ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::rcv_struct_inform_of_unexpected_response(), ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::send_impl(), ipc::session::shm::arena_lend::jemalloc::Session_impl< Session_impl_t >::session_shm_builder_config(), and ipc::session::shm::classic::Session_impl< Session_impl_t >::shm_builder_config().
| const Null_session ipc::transport::struc::NULL_SESSION |
The only necessary value of empty-type Null_session.
Definition at line 36 of file heap_serializer.cpp.
Referenced by ipc::transport::struc::shm::Builder< Shm_arena >::emit_serialization().
| const Session_token ipc::transport::struc::NULL_SESSION_TOKEN = boost::uuids::nil_uuid() |
A value for which .is_nil() is true.
Definition at line 35 of file channel.cpp.
Referenced by ipc::session::Client_session_impl< MQ_TYPE_OR_NONE, TRANSMIT_NATIVE_HANDLES, Mdt_payload, SHM_TYPE_OR_NONE, GRACEFUL_FINISH_REQUIRED >::session_token(), 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 >::session_token(), ipc::session::Session_mv< Session_impl_t >::session_token(), and ipc::transport::struc::sync_io::Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t >::session_token().
1.9.4