Flow-IPC 1.0.0
Flow-IPC project: Full implementation reference.
transport_fwd.hpp
Go to the documentation of this file.
1/* Flow-IPC: Core
2 * Copyright 2023 Akamai Technologies, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the
5 * "License"); you may not use this file except in
6 * compliance with the License. You may obtain a copy
7 * of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in
12 * writing, software distributed under the License is
13 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
14 * CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing
16 * permissions and limitations under the License. */
17
18/// @file
19#pragma once
20
23
24/**
25 * Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more)
26 * between pairs of processes. See namespace ::ipc doc header for an overview of Flow-IPC modules including
27 * how ipc::transport relates to the others. Then return here. A synopsis follows:
28 *
29 * The main transport features of ipc::transport are: class template struc::Channel (for structured message and
30 * native handle transport) and various lower-level utilities (Channel; blob/handle streams; message queue
31 * (MQ) streams). Structured transmission facilities (struc::Channel being the main guy) are segregated in
32 * sub-namespace transport::struc.
33 *
34 * Generally speaking, to communicate (via struc::Channel and others), the two processes A and B that intend to
35 * talk must have established a broad conversation called a *session* within which all communication occurs.
36 * In fact, a transport::struc::Channel wraps a transport::Channel, and the latter can be established, in factory-ish
37 * fashion and otherwise, from an ipc::session::Session. Hence, see namespace ipc::session doc header to learn about
38 * establishing/terminating sessions. Once you have a session::Session, you can actually use main ipc::transport
39 * facilities.
40 *
41 * That said: ipc::transport does *not* require ipc::session to be used: One can instantiate all the various IPC
42 * mechanisms therein directly. ipc::session provides the lifecycle and organization to make this as simple as
43 * possible (but no simpler). In that sense ipc::transport has the essential building blocks; ipc::session provides
44 * access to those building blocks in one possible fashion -- for example by establishing a naming convention
45 * for the various required `Shared_name`s taken by the various ipc::transport constructors. Formally speaking
46 * there can certainly be other fashions of organizing ipc::transport resources. Therefore the API design of
47 * ipc::transport is not rigid.
48 */
49namespace ipc::transport
50{
51
52// Types.
53
54// Find doc headers near the bodies of these compound types.
55
56class Native_socket_stream;
57class Native_socket_stream_acceptor;
58class Posix_mq_handle;
59class Bipc_mq_handle;
60template<typename Persistent_mq_handle>
61class Blob_stream_mq_sender;
62template<typename Persistent_mq_handle>
63class Blob_stream_mq_receiver;
64class Null_peer;
65template<typename Blob_sender, typename Blob_receiver, typename Native_handle_sender, typename Native_handle_receiver>
66class Channel;
67template<bool SIO>
68class Socket_stream_channel;
69template<bool SIO>
70class Socket_stream_channel_of_blobs;
71template<bool SIO,
72 typename Persistent_mq_handle,
73 typename Native_handle_sender = Null_peer, typename Native_handle_receiver = Null_peer>
74class Mqs_channel;
75template<bool SIO,
76 typename Persistent_mq_handle>
77class Mqs_socket_stream_channel;
78class Protocol_negotiator;
79
80/// Convenience alias for the commonly used type util::Native_handle.
82
83/// Convenience alias for the commonly used type util::Shared_name.
85
86/**
87 * Convenience alias: Blob_sender via unidirectional POSIX MQ (message queue).
88 *
89 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
90 */
92
93/**
94 * Convenience alias: Blob_receiver via unidirectional POSIX MQ (message queue).
95 *
96 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
97 */
99
100/**
101 * Convenience alias: Blob_sender via unidirectional bipc MQ (message queue).
102 *
103 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
104 */
106
107/**
108 * Convenience alias: Blob_receiver via unidirectional bipc MQ (message queue).
109 *
110 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
111 */
113
114/**
115 * Convenience alias: Channel peer (Blob_sender, Blob_receiver) at one end of full-duplex (bidirectional) pipe
116 * composed of 2 opposite-facing unidirectional POSIX MQs (message queues).
117 *
118 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
119 */
121
122/**
123 * Convenience alias: Channel peer (Blob_sender, Blob_receiver) at one end of full-duplex (bidirectional) pipe
124 * composed of 2 opposite-facing unidirectional POSIX MQs (message queues).
125 *
126 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
127 */
129
130/**
131 * Convenience alias: Channel peer (Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver)
132 * at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs
133 * (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain stream connection,
134 * transmitting native-handle-and/or-meta-blob messages.
135 *
136 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
137 */
139
140/**
141 * Convenience alias: Channel peer (Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver)
142 * at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional bipc MQs
143 * (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain stream connection,
144 * transmitting native-handle-and/or-meta-blob messages.
145 *
146 * Tip: In `sync_io` sub-namespace there is the `sync_io`-pattern counterpart.
147 */
149
150// Free functions.
151
152/**
153 * Prints string representation of the given `Native_socket_stream` to the given `ostream`.
154 *
155 * @relatesalso Native_socket_stream
156 *
157 * @param os
158 * Stream to which to write.
159 * @param val
160 * Object to serialize.
161 * @return `os`.
162 */
163std::ostream& operator<<(std::ostream& os, const Native_socket_stream& val);
164
165/**
166 * Prints string representation of the given `Native_socket_stream_acceptor` to the given `ostream`.
167 *
168 * @relatesalso Native_socket_stream_acceptor
169 *
170 * @param os
171 * Stream to which to write.
172 * @param val
173 * Object to serialize.
174 * @return `os`.
175 */
176std::ostream& operator<<(std::ostream& os, const Native_socket_stream_acceptor& val);
177
178/**
179 * Prints string representation of the given `Blob_stream_mq_receiver` to the given `ostream`.
180 *
181 * If object is default-cted (or moved-from), this will output something graceful indicating this.
182 *
183 * @relatesalso Blob_stream_mq_receiver
184 *
185 * @param os
186 * Stream to which to write.
187 * @param val
188 * Object to serialize.
189 * @return `os`.
190 */
191template<typename Persistent_mq_handle>
192std::ostream& operator<<(std::ostream& os, const Blob_stream_mq_receiver<Persistent_mq_handle>& val);
193
194/**
195 * Prints string representation of the given `Blob_stream_mq_sender` to the given `ostream`.
196 *
197 * If object is default-cted (or moved-from), this will output something graceful indicating this.
198 *
199 * @relatesalso Blob_stream_mq_sender
200 *
201 * @param os
202 * Stream to which to write.
203 * @param val
204 * Object to serialize.
205 * @return `os`.
206 */
207template<typename Persistent_mq_handle>
208std::ostream& operator<<(std::ostream& os, const Blob_stream_mq_sender<Persistent_mq_handle>& val);
209
210/**
211 * Prints string representation of the given Bipc_mq_handle to the given `ostream`.
212 *
213 * @relatesalso Bipc_mq_handle
214 *
215 * @param os
216 * Stream to which to write.
217 * @param val
218 * Object to serialize.
219 * @return `os`.
220 */
221std::ostream& operator<<(std::ostream& os, const Bipc_mq_handle& val);
222
223/**
224 * Prints string representation of the given Posix_mq_handle to the given `ostream`.
225 *
226 * @relatesalso Posix_mq_handle
227 *
228 * @param os
229 * Stream to which to write.
230 * @param val
231 * Object to serialize.
232 * @return `os`.
233 */
234std::ostream& operator<<(std::ostream& os, const Posix_mq_handle& val);
235
236/**
237 * Prints string representation of the given `Channel` to the given `ostream`.
238 *
239 * @relatesalso Channel
240 *
241 * @param os
242 * Stream to which to write.
243 * @param val
244 * Object to serialize.
245 * @return `os`.
246 */
247template<typename Blob_sender, typename Blob_receiver, typename Native_handle_sender, typename Native_handle_receiver>
248std::ostream& operator<<(std::ostream& os,
250
251/**
252 * Dummy that is never invoked. It must still exist in order for Channel to build successfully with at least 1
253 * Null_peer template arg.
254 *
255 * Assertion may trip if this is invoked. Formally behavior is undefined.
256 *
257 * @relatesalso Null_peer
258 *
259 * @param os
260 * Stream to which to write.
261 * @param val
262 * Object to serialize.
263 * @return `os`.
264 */
265std::ostream& operator<<(std::ostream& os, const Null_peer& val);
266
267/**
268 * Implements Persistent_mq_handle related concept: Swaps two objects.
269 *
270 * @relatesalso Bipc_mq_handle
271 *
272 * @param val1
273 * Object.
274 * @param val2
275 * Object.
276 */
277void swap(Bipc_mq_handle& val1, Bipc_mq_handle& val2);
278
279/**
280 * Implements Persistent_mq_handle related concept: Swaps two objects.
281 *
282 * @relatesalso Posix_mq_handle
283 *
284 * @param val1
285 * Object.
286 * @param val2
287 * Object.
288 */
289void swap(Posix_mq_handle& val1, Posix_mq_handle& val2);
290
291} // namespace ipc::transport
292
293/**
294 * `sync_io`-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.
295 * For example transport::sync_io::Native_socket_stream <=> transport::Native_socket_stream.
296 *
297 * @see util::sync_io doc header -- describes the general `sync_io` pattern we are following.
298 */
300{
301
302// Types.
303
304// Find doc headers near the bodies of these compound types.
305class Native_socket_stream;
306class Native_socket_stream_acceptor;
307template<typename Persistent_mq_handle>
308class Blob_stream_mq_sender;
309template<typename Persistent_mq_handle>
310class Blob_stream_mq_receiver;
311
312/// Convenience alias: sync_io::Blob_sender via unidirectional POSIX MQ (message queue).
314/// Convenience alias: sync_io::Blob_receiver via unidirectional POSIX MQ (message queue).
316/// Convenience alias: sync_io::Blob_sender via unidirectional bipc MQ (message queue).
318/// Convenience alias: sync_io::Blob_receiver via unidirectional bipc MQ (message queue).
320
321/**
322 * Convenience alias: Channel peer (sync_io::Blob_sender, sync_io::Blob_receiver) at one end of full-duplex
323 * (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues).
324 */
326
327/**
328 * Convenience alias: Channel peer (sync_io::Blob_sender, sync_io::Blob_receiver) at one end of full-duplex
329 * (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues).
330 */
332
333/**
334 * Convenience alias: Channel peer (sync_io::Blob_sender, sync_io::Blob_receiver, sync_io::Native_handle_sender,
335 * sync_io::Native_handle_receiver) at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing
336 * unidirectional POSIX MQs (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain
337 * stream connection, transmitting native-handle-and/or-meta-blob messages.
338 */
340
341/**
342 * Convenience alias: Channel peer (sync_io::Blob_sender, sync_io::Blob_receiver, sync_io::Native_handle_sender,
343 * sync_io::Native_handle_receiver) at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing
344 * unidirectional bipc MQs (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain
345 * stream connection, transmitting native-handle-and/or-meta-blob messages.
346 */
348
349// Free functions.
350
351/**
352 * Prints string representation of the given `Native_socket_stream` to the given `ostream`.
353 *
354 * @relatesalso Native_socket_stream
355 *
356 * @param os
357 * Stream to which to write.
358 * @param val
359 * Object to serialize.
360 * @return `os`.
361 */
362std::ostream& operator<<(std::ostream& os, const Native_socket_stream& val);
363
364/**
365 * Prints string representation of the given `Native_socket_stream_acceptor` to the given `ostream`.
366 *
367 * @relatesalso Native_socket_stream_acceptor
368 *
369 * @param os
370 * Stream to which to write.
371 * @param val
372 * Object to serialize.
373 * @return `os`.
374 */
375std::ostream& operator<<(std::ostream& os, const Native_socket_stream_acceptor& val);
376
377/**
378 * Prints string representation of the given `Blob_stream_mq_sender` to the given `ostream`.
379 *
380 * If object is default-cted (or moved-from), this will output something graceful indicating this.
381 *
382 * @relatesalso Blob_stream_mq_sender
383 *
384 * @param os
385 * Stream to which to write.
386 * @param val
387 * Object to serialize.
388 * @return `os`.
389 */
390template<typename Persistent_mq_handle>
391std::ostream& operator<<(std::ostream& os, const Blob_stream_mq_sender<Persistent_mq_handle>& val);
392
393/**
394 * Prints string representation of the given `Blob_stream_mq_receiver` to the given `ostream`.
395 *
396 * If object is default-cted (or moved-from), this will output something graceful indicating this.
397 *
398 * @relatesalso Blob_stream_mq_receiver
399 *
400 * @param os
401 * Stream to which to write.
402 * @param val
403 * Object to serialize.
404 * @return `os`.
405 */
406template<typename Persistent_mq_handle>
407std::ostream& operator<<(std::ostream& os, const Blob_stream_mq_receiver<Persistent_mq_handle>& val);
408
409} // namespace ipc::transport::sync_io
Implements the Persistent_mq_handle concept by thinly wrapping bipc::message_queue,...
Implements Blob_receiver concept by using an adopted Persistent_mq_handle MQ handle to an MQ (message...
Implements Blob_sender concept by using an adopted Persistent_mq_handle MQ handle to an MQ (message q...
Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...
Definition: channel.hpp:308
A Channel with at least a blobs pipe consisting of two MQs of type Persistent_mq_handle (template arg...
Definition: channel.hpp:1180
A Channel with a blobs pipe consisting of 2 MQs of type Persistent_mq_handle (template arg); and a ha...
Definition: channel.hpp:1278
A server object that binds to a Shared_name and listens for incoming Native_socket_stream connect att...
Implements both Native_handle_sender and Native_handle_receiver concepts by using a stream-oriented U...
Dummy type for use as a template param to Channel when either the blobs pipe or handles pipe is disab...
Definition: channel.hpp:1000
Implements the Persistent_mq_handle concept by wrapping the POSIX message queue API (see man mq_overv...
Implements sync_io::Blob_receiver concept by using an adopted Persistent_mq_handle MQ handle to an MQ...
Implements sync_io::Blob_sender concept by using an adopted Persistent_mq_handle MQ handle to an MQ (...
sync_io-pattern counterpart to async-I/O-pattern transport::Native_socket_stream_acceptor.
Implements both sync_io::Native_handle_sender and sync_io::Native_handle_receiver concepts by using a...
String-wrapping abstraction representing a name uniquely distinguishing a kernel-persistent entity fr...
struc::Channel< Channel_obj, Message_body, Builder::Config, Reader::Config > Channel
Convenience alias: Use this when constructing a struc::Channel with tag Channel_base::S_SERIALIZE_VIA...
Definition: classic.hpp:42
sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.
std::ostream & operator<<(std::ostream &os, const Blob_stream_mq_receiver_impl< Persistent_mq_handle > &val)
Prints string representation of the given Blob_stream_mq_receiver_impl to the given ostream.
Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...
util::Shared_name Shared_name
Convenience alias for the commonly used type util::Shared_name.
std::ostream & operator<<(std::ostream &os, const Bipc_mq_handle &val)
Prints string representation of the given Bipc_mq_handle to the given ostream.
util::Native_handle Native_handle
Convenience alias for the commonly used type util::Native_handle.
void swap(Bipc_mq_handle &val1, Bipc_mq_handle &val2)
Implements Persistent_mq_handle related concept: Swaps two objects.
A monolayer-thin wrapper around a native handle, a/k/a descriptor a/k/a FD.