c++-gtk-utils

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

pipes.h
Go to the documentation of this file.
1 /* Copyright (C) 1999 to 2004, and 2009 to 2011 Chris Vine
2
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public License
9 as published by the Free Software Foundation; either version 2.1 of
10 the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License, version 2.1, for more details.
16
17 You should have received a copy of the GNU Lesser General Public
18 License, version 2.1, along with this library (see the file LGPL.TXT
19 which came with this source code package in the c++-gtk-utils
20 sub-directory); if not, write to the Free Software Foundation, Inc.,
21 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22
23 */
24
25 #ifndef CGU_PIPES_H
26 #define CGU_PIPES_H
27
28 #include <unistd.h>
29
30 #include <exception>
31
32 #include <c++-gtk-utils/cgu_config.h>
33
34 namespace Cgu {
35
36 /**
37 * @class PipeFifo pipes.h c++-gtk-utils/pipes.h
38 * @brief A wrapper for unix anonymous pipes.
39 * @sa SyncPipe
40 *
41 * This class provides a simplified front end for anonymous fifo pipes
42 * (as created by the pipe() system call). The constructor of the
43 * class may be passed an enumerator to indicate whether the pipe is
44 * to read in non-blocking mode.
45 *
46 * With the write(const char*, int) method, taking an array and int
47 * arguments, the value of int (indicating the number of chars in the
48 * array to be written) should usually be less than PIPE_BUF, as POSIX
49 * write() guarantees that if it is less than PIPE_BUF, either all
50 * will be written or, if the pipe is too full, none will be written.
51 * This prevents data interleaving if a number of independent writes
52 * to the fifo are made. The same is true of the write (const char*)
53 * method taking a string - if the string is longer than PIPE_BUF in
54 * size, data interleaving may occur.
55 *
56 * The pipe is set to read in non-blocking mode if the constructor of
57 * PipeFifo, or PipeFifo::open(), is passed the value
58 * PipeFifo::non_block. If constructed in this way, the pipe can also
59 * be set to write in non-block mode (eg to minimise the impact on
60 * another program running in a child process to which the child
61 * process has exec()ed when monitoring its stdin or stderr) by
62 * calling make_write_non_block(). However use this very sparingly --
63 * when set in this way write() will always try to write something.
64 * The atomic guarantees mentioned in the preceding paragraph do not
65 * apply and data can be interleaved or lost.
66 *
67 * PIPE_BUF is defined in limits.h, and is at least 512 bytes, and
68 * usually 4096 bytes, but may be calculated from other files included
69 * by limits.h.
70 *
71 * Where a pipe is used to communicate between parent and child after
72 * a call to fork(), the pipe will normally be used unidirectionally
73 * unless guards or semaphores are used to prevent a process reading
74 * data intended for the other. However, because each process
75 * inherits its own duplicate of the file descriptors, this cannot be
76 * enforced without closing the read or write file descriptor for the
77 * process for which the reading or writing is to be prohibited. This
78 * can be done by the process concerned calling the methods
79 * PipeFifo::make_writeonly() or PipeFifo::make_readonly() after the
80 * fork. If an attempt is made to read or write to a descriptor
81 * closed in this way, the PipeFifo::read() or PipeFifo::write()
82 * method will ensure that no read or write will take place, and
83 * instead -2 will be returned.
84 *
85 * The methods PipeFifo::connect_to_stdin(),
86 * PipeFifo::connect_to_stdout() and PipeFifo::connect_to_stderr() are
87 * available to be used in the child process before it exec()s another
88 * program so as to connect the pipe to that program's stdin, stdout
89 * or stderr. PipeFifo::connect_to_stdin() cannot be used by a
90 * process after that process has called PipeFifo::make_writeonly(),
91 * and PipeFifo::connect_to_stdout() and PipeFifo::connect_to_stderr()
92 * cannot be used after the process has called
93 * PipeFifo::make_readonly(), nor can a pipe in any one process be
94 * connected to more than one of stdin, stdout or stderr. If that is
95 * attempted the methods will return -2. Furthermore, they should
96 * only be used after the process creating the pipe has forked. If
97 * the connection to stdin, stdout or stderr is to be made before the
98 * fork, this must be done by hand using dup2(),
99 * PipeFifo::get_write_fd()/ PipeFifo::get_read_fd() and
100 * PipeFifo::make_read_only()/ PipeFifo::make_write_only().
101 *
102 * If PipeFifo::connect_to_stdin() is called by a method,
103 * PipeFifo::make_readonly() will also be called, and if
104 * PipeFifo::connect_to_stdout() or PipeFifo::connect_to_stderr() are
105 * called, PipeFifo::make_writeonly() will also be called. This will
106 * isolate the use of the pipe by the child process to stdin, stdout
107 * or stderr, as appropriate.
108 *
109 * It uses no static members, so is thread safe as between different
110 * objects, but its methods are not thread safe as regards any one
111 * object in the sense that the read() and write() methods check the
112 * value of read_fd and write_fd respectively (and get_read_fd() and
113 * get_write_fd() return them), and make_writeonly(), make_readonly(),
114 * close(), connect_to_stdin(), open(), connect_to_stdout() and
115 * connect_to_stderr() change those values. Likewise the read() and
116 * write() methods access read_blocking_mode and write_blocking_mode
117 * respectively, and these are changed by open() and
118 * make_write_non_block(). Provided there is no concurrent use of
119 * read(), write(), get_read_fd() or get_write_fd() in one thread with
120 * a call of a method which changes read_fd, write_fd,
121 * read_blocking_mode or write_blocking_mode as described above in
122 * another thread then no mutex is required to ensure thread safety.
123 *
124 * All the read() and write() methods check for an interruption of the
125 * system call from a signal (EINTR is checked), and will continue to
126 * read() or write() where necessary. Users do not need to check
127 * EINTR themselves. Where the write file descriptor is flagged as
128 * blocking (that is, where PipeFifo::make_write_non_block() has not
129 * been called), then in the absence of some other error, everything
130 * passed to PipeFifo::write() will be written (but as mentioned above
131 * there may be data interleaving if this is greater than PIPE_BUF in
132 * size). Where the write file descriptor is flagged as non-blocking,
133 * then the result of Unix write is returned, and less bytes than
134 * those passed to PipeFifo::write() may have been written, or -1 may
135 * be returned with errno set to EAGAIN - it is for the user to check
136 * this.
137 *
138 * If you are using pipes to write and read between processes, you
139 * will probably want to call sigaction() to cause the SIGPIPE signal
140 * to be ignored. SIGPIPE has little use in most programming: if
141 * SIGPIPE is ignored, and an attempt is made to write to a pipe which
142 * has been closed at the read end, then the write will return -1 and
143 * errno will be set to EPIPE.
144 */
145
146 struct PipeError: public std::exception {
147 virtual const char* what() const throw() {return "PipeError: error opening pipe\n";}
148 };
149
150 class PipeFifo {
151 public:
152 enum Fifo_mode{block, non_block};
153 private:
154 int read_fd;
155 int write_fd;
156 Fifo_mode read_blocking_mode;
157 Fifo_mode write_blocking_mode;
158
159 public:
160 /**
161 * This class cannot be copied. The copy constructor is deleted.
162 */
163 PipeFifo(const PipeFifo&) = delete;
164
165 /**
166 * This class cannot be copied. The assignment operator is deleted.
167 */
168 PipeFifo& operator=(const PipeFifo&) = delete;
169
170 /**
171 * Opens read and write file descriptors for the pipe. If the pipe is
172 * already open, it will close the existing file descriptors. This
173 * function call is thread-safe to the extent that all the system
174 * calls made in its implementation are async-signal-safe, so it may
175 * safely be called in a multi-threaded program after a fork() and
176 * before an exec(). However, the manipulation of the file
177 * descriptors and related variables is not protected by a mutex, so
178 * if different threads in the same process are to manipulate the same
179 * pipe object with this method, close(), connect_to_stdin(),
180 * connect_to_stdout() or connect_to_stderr() (which manipulate both
181 * descriptors), make_readonly() or make_write_non_block() (which
182 * manipulate the write file descriptor), or make_writeonly() (which
183 * manipulates the read file descriptor), or read the value of the
184 * file descriptor with get_read_fd() or read() (which access the read
185 * file descriptor) or get_write_fd() or write() (which access the
186 * write file descriptor) concurrently with such a manipulation, then
187 * the user should provide appropriate synchronisation.
188 * @param mode The mode in which the read file descriptor of the pipe
189 * is to be opened - either Cgu::PipeFifo::block or
190 * Cgu::PipeFifo::non_block.
191 * @exception Cgu::PipeError This exception is thrown if the opening
192 * of the pipe fails. No other exceptions will be thrown.
193 */
194 void open(Fifo_mode mode);
195
196 /**
197 * Closes the read and write file descriptors of the pipe (if they are
198 * open). This function call is thread-safe to the extent that all
199 * the system calls made in its implementation are async-signal-safe,
200 * so it may safely be called in a multi-threaded program after a
201 * fork() and before an exec(). However, the manipulation of the file
202 * descriptors and related variables is not protected by a mutex, so
203 * if different threads in the same process are to manipulate the same
204 * pipe object with this method, open(), connect_to_stdin(),
205 * connect_to_stdout() or connect_to_stderr() (which manipulate both
206 * descriptors), make_readonly() or make_write_non_block() (which
207 * manipulate the write file descriptor), or make_writeonly() (which
208 * manipulates the read file descriptor), or read the value of the
209 * file descriptor with get_read_fd() or read() (which access the read
210 * file descriptor) or get_write_fd() or write() (which access the
211 * write file descriptor) concurrently with such a manipulation, then
212 * the user should provide appropriate synchronisation. No exceptions
213 * will be thrown.
214 */
215 void close();
216
217 /**
218 * Reads up to max_num characters from the pipe. This read does not
219 * carry on blocking until the read request is met: unless there is an
220 * interrupt, it just calls POSIX read() once and takes what is
221 * available. If a specific number of characters is required, the
222 * user should provide an appropriate do/while loop. It does not
223 * throw. Any reasonable POSIX implementation will do an atomic read
224 * as between threads if max_num is PIPE_BUF or less in size, but the
225 * POSIX standard only requires such atomic reads as between processes
226 * rather than as between threads. The user does not need to check
227 * for EINTR and an interrupt: this method deals with that
228 * automatically. All the system calls made in its implementation are
229 * async-signal-safe, and it is re-entrant subject to errno being
230 * saved. This method does not throw.
231 * @param buf A buffer into which the characters will be placed.
232 * @param max_num The maximum number of characters to be read
233 * (normally the size of the buffer).
234 * @return -2 if the read file descriptor is invalid, otherwise the
235 * result of unix read() - that is, the number of characters read, or
236 * 0 if end of file is reached (ie the write descriptor has been
237 * closed), or -1 if there has been an error (but EINTR never returns
238 * as an error as the implementation handles that). In the event of
239 * an error, errno is set.
240 */
241 ssize_t read(char* buf, size_t max_num);
242
243 /**
244 * Extracts a character from the pipe. This method does not throw.
245 * All the system calls made in its implementation are
246 * async-signal-safe and it is re-entrant subject to errno being
247 * saved. It is thread safe.
248 * @return The character at the front of the pipe if available,
249 * otherwise -2 if the read file descriptor is invalid, 0 if end of
250 * file is reached (ie the write descriptor has been closed), or -1 if
251 * there has been an error (but EINTR never returns as an error as the
252 * implementation handles that). In the event of an error, errno is
253 * set.
254 */
255 int read();
256
257 /**
258 * Write a NUL terminated C string to the pipe, excluding the
259 * terminating NUL character. If the write file descriptor is set as
260 * blocking (the default) then this method will carry on blocking
261 * until everything is sent, even if it exceeds PIPE_BUF in size. Any
262 * reasonable POSIX implementation will do an atomic write (with no
263 * interleaving) as between threads if the number of characters in the
264 * string is PIPE_BUF or less in size, but the POSIX standard only
265 * requires such atomic writes as between processes rather than as
266 * between threads. All the system calls made in its implementation
267 * are async-signal-safe and it is re-entrant subject to errno being
268 * saved. This method does not throw.
269 * @param str The string to be written.
270 * @return -2 if write file descriptor invalid, otherwise it returns
271 * the number of bytes written or -1 if there has been an error (but
272 * EINTR never returns as an error as the implementation handles
273 * that). In the event of an error, errno is set.
274 */
275 ssize_t write(const char* str);
276
277 /**
278 * Write a buffer of characters to the pipe. If the write file
279 * descriptor is set as blocking (the default) then this method will
280 * carry on blocking until everything is sent, even if it exceeds
281 * PIPE_BUF in size. Any reasonable POSIX implementation will do an
282 * atomic write (with no interleaving) as between threads if num is
283 * PIPE_BUF or less in size, but the POSIX standard only requires such
284 * atomic writes as between processes rather than as between threads.
285 * All the system calls made in its implementation are
286 * async-signal-safe and it is re-entrant subject to errno being
287 * saved. This method does not throw.
288 * @param buf The buffer to be written.
289 * @param num The number of characters in the buffer.
290 * @return -2 if write file descriptor invalid, otherwise it returns
291 * the number of bytes written or -1 if there has been an error (but
292 * EINTR never returns as an error as the implementation handles
293 * that). In the event of an error, errno is set.
294 */
295 ssize_t write(const char* buf, size_t num);
296
297 /**
298 * Write a character to the pipe. All the system calls made in its
299 * implementation are async-signal-safe and it is re-entrant subject
300 * to errno being saved. This method does not throw. It is thread
301 * safe.
302 * @param item The character to be written.
303 * @return 1 if the character was written, -2 if the write file
304 * descriptor is invalid, or -1 if there has been an error (but EINTR
305 * never returns as an error as the implementation handles that). In
306 * the event of an error, errno is set.
307 */
308 int write(char item) {return write(&item, 1);}
309
310 /**
311 * Make the pipe only available for writing in the calling process, by
312 * closing the read file descriptor. This function call is thread
313 * safe to the extent that all the system calls made in its
314 * implementation are async-signal-safe, so it may safely be called in
315 * a multi-threaded program after a fork() and before an exec().
316 * However, the manipulation of the file descriptor and related
317 * variables is not protected by a mutex, so if different threads in
318 * the same process are to manipulate the same pipe object with
319 * open(), close(), connect_to_stdin(), connect_to_stdout() or
320 * connect_to_stderr() (which manipulate both descriptors), or this
321 * method (which manipulates the read file descriptor), or read the
322 * value of the read file descriptor with get_read_fd() or read()
323 * concurrently with such a manipulation, then the user should provide
324 * appropriate synchronisation. No exceptions will be thrown.
325 */
326 void make_writeonly();
327
328 /**
329 * Make the pipe only available for reading in the calling process, by
330 * closing the write file descriptor. This function call is
331 * thread-safe to the extent that all the system calls made in its
332 * implementation are async-signal-safe, so it may safely be called in
333 * a multi-threaded program after a fork() and before an exec().
334 * However, the manipulation of the file descriptor and related
335 * variables is not protected by a mutex, so if different threads in
336 * the same process are to manipulate the same pipe object with
337 * open(), close(), connect_to_stdin(), connect_to_stdout() or
338 * connect_to_stderr() (which manipulate both descriptors), or this
339 * method or make_write_non_block() (which manipulate the write file
340 * descriptor), or read the value of the write file descriptor with
341 * get_write_fd() or write() concurrently with such a manipulation,
342 * then the user should provide appropriate synchronisation. No
343 * exceptions will be thrown.
344 */
345 void make_readonly();
346
347 /**
348 * Makes the write file descriptor non-blocking. This is only very
349 * rarely needed. If the write file descriptor is set non-blocking,
350 * then there are no atomic write guarantees. This function call is
351 * thread safe to the extent that all the system calls made in its
352 * implementation are async-signal-safe, so it may safely be called in
353 * a multi-threaded program after a fork() and before an exec().
354 * However, the manipulation of the file descriptor and related
355 * variables is not protected by a mutex, so if different threads in
356 * the same process are to manipulate the same pipe object with
357 * open(), close(), connect_to_stdin(), connect_to_stdout() or
358 * connect_to_stderr() (which manipulate both descriptors), or this
359 * method or make_readonly() (which manipulate the write file
360 * descriptor), or read the value of the write file descriptor with
361 * get_write_fd() or write() concurrently with such a manipulation,
362 * then the user should provide appropriate synchronisation. No
363 * exceptions will be thrown.
364 * @return 0 if the write file descriptor is open, or -1 otherwise.
365 */
366 int make_write_non_block();
367
368 /**
369 * Get the read file descriptor (if any). The fetching of the file
370 * descriptor is not protected by a mutex, so if different threads in
371 * the same process are to manipulate the same pipe object with
372 * open(), close(), connect_to_stdin(), connect_to_stdout() or
373 * connect_to_stderr() (which manipulate both descriptors), or
374 * make_writeonly() (which manipulates the read file descriptor), or
375 * read the value of the file descriptor with this method or read()
376 * concurrently with such a manipulation, then the user should provide
377 * appropriate synchronisation. No exceptions will be thrown.
378 * @return The read file descriptor, or -1 is none is open.
379 */
380 int get_read_fd() const {return read_fd;}
381
382 /**
383 * Get the write file descriptor (if any). The fetching of the file
384 * descriptor is not protected by a mutex, so if different threads in
385 * the same process are to manipulate the same pipe object with
386 * open(), close(), connect_to_stdin(), connect_to_stdout() or
387 * connect_to_stderr() (which manipulate both descriptors), or
388 * make_readonly() or make_write_non_block() (which manipulate the
389 * write file descriptor), or read the value of the file descriptor
390 * with this method or write() concurrently with such a manipulation,
391 * then the user should provide appropriate synchronisation. No
392 * exceptions will be thrown.
393 * @return The write file descriptor, or -1 is none is open.
394 */
395 int get_write_fd() const {return write_fd;}
396
397 /**
398 * Connect the read file descriptor of the pipe to stdin. Once
399 * called, any read from stdin in the process which calls this method
400 * will be read from the pipe. It should only be called in a child
401 * process or parent process after a fork() where the PipeFifo object
402 * has been created in the parent process, and typically is called by
403 * the child process before one of the exec() functions is invoked by
404 * the child process. It should only be called once, and cannot be
405 * called after connect_to_stdout(), connect_to_stderr() or
406 * make_writeonly() has been called in the same process. Once called,
407 * the write file descriptor is no longer available to the process
408 * calling this method. Typically it would be used in order that when
409 * the new process image created by exec() reads from stdin, it reads
410 * from the pipe, and the parent process (or another child process)
411 * writes to the pipe. This function call is thread safe to the
412 * extent that all the system calls made in its implementation are
413 * async-signal-safe, so it may safely be called in a multi-threaded
414 * program after a fork() and before an exec(). However, the
415 * manipulation of the file descriptors and related variables is not
416 * protected by a mutex, so if different threads in the same process
417 * are to manipulate the same pipe object with this method, open(),
418 * close(), connect_to_stdout() or connect_to_stderr() (which
419 * manipulate both descriptors), make_readonly() or
420 * make_write_non_block() (which manipulate the write file
421 * descriptor), or make_writeonly() (which manipulates the read file
422 * descriptor), or read the value of the file descriptor with
423 * get_read_fd() or read() (which access the read file descriptor) or
424 * get_write_fd() or write() (which access the write file descriptor)
425 * concurrently with such a manipulation, then the user should provide
426 * appropriate synchronisation. It does not throw.
427 * @return -2 if the read file descriptor has previously been closed
428 * or this method, connect_to_stdout() or connect_to_stderr() has
429 * previously been called in the same process, otherwise it returns
430 * the value returned by dup2(), that is 0 if the operation succeeds,
431 * or -1 (with errno set) if not. It does not throw.
432 */
433 int connect_to_stdin();
434
435 /**
436 * Connect the write file descriptor of the pipe to stdout. Once
437 * called, any write to stdout in the process which calls this method
438 * will be written to the pipe. It should only be called in a child
439 * or parent process after a fork() where the PipeFifo object has been
440 * created in the parent process, and typically is called by the child
441 * process before one of the exec() functions is invoked by the child
442 * process. It should only be called once, and cannot be called after
443 * connect_to_stdin(), connect_to_stderr() or make_readonly() has been
444 * called in the same process. Once called, the read file descriptor
445 * is no longer available to the process calling this method.
446 * Typically it would be used in order that when the new process image
447 * created by exec() writes to stdout, it writes to the pipe, and the
448 * parent process (or another child process) reads from the pipe.
449 * This function call is thread safe to the extent that all the system
450 * calls made in its implementation are async-signal-safe, so it may
451 * safely be called in a multi-threaded program after a fork() and
452 * before an exec(). However, the manipulation of the file
453 * descriptors and related variables is not protected by a mutex, so
454 * if different threads in the same process are to manipulate the same
455 * pipe object with this method, open(), close(), connect_to_stdin()
456 * or connect_to_stderr() (which manipulate both descriptors),
457 * make_readonly() or make_write_non_block() (which manipulate the
458 * write file descriptor), or make_writeonly() (which manipulates the
459 * read file descriptor), or read the value of the file descriptor
460 * with get_read_fd() or read() (which access the read file
461 * descriptor) or get_write_fd() or write() (which access the write
462 * file descriptor) concurrently with such a manipulation, then the
463 * user should provide appropriate synchronisation. It does not
464 * throw.
465 * @return -2 if the write file descriptor has previously been closed
466 * or this method, connect_to_stdin() or connect_to_stderr() has
467 * previously been called in the same process, otherwise it returns
468 * the value returned by dup2(), that is 0 if the operation succeeds,
469 * or -1 (with errno set) if not. It does not throw.
470 */
471 int connect_to_stdout();
472
473 /**
474 * Connect the write file descriptor of the pipe to stderr. Once
475 * called, any write to stderr in the process which calls this method
476 * will be written to the pipe. It should only be called in a child
477 * or parent process after a fork() where the PipeFifo object has been
478 * created in the parent process, and typically is called by a child
479 * process before one of the exec() functions is invoked by the child
480 * process. It should only be called once, and cannot be called after
481 * connect_to_stdin(), connect_to_stdout() or make_readonly() has been
482 * called in the same process. Once called, the read file descriptor
483 * is no longer available to the process calling this method.
484 * Typically it would be used in order that when the new process image
485 * created by exec() writes to stderr, it writes to the pipe, and the
486 * parent process (or another child process) reads from the pipe.
487 * This function call is thread safe to the extent that all the system
488 * calls made in its implementation are async-signal-safe, so it may
489 * safely be called in a multi-threaded program after a fork() and
490 * before an exec(). However, the manipulation of the file
491 * descriptors and related variables is not protected by a mutex, so
492 * if different threads in the same process are to manipulate the same
493 * pipe object with this method, open(), close(), connect_to_stdin()
494 * or connect_to_stdout() (which manipulate both descriptors),
495 * make_readonly() or make_write_non_block() (which manipulate the
496 * write file descriptor), or make_writeonly() (which manipulates the
497 * read file descriptor), or read the value of the file descriptor
498 * with get_read_fd() or read() (which access the read file
499 * descriptor) or get_write_fd() or write() (which access the write
500 * file descriptor) concurrently with such a manipulation, then the
501 * user should provide appropriate synchronisation. It does not
502 * throw.
503 * @return -2 if the write file descriptor has previously been closed
504 * or this method, connect_to_stdin() or connect_to_stdout() has
505 * previously been called in the same process, otherwise it returns
506 * the value returned by dup2(), that is 0 if the operation succeeds,
507 * or -1 (with errno set) if not. It does not throw.
508 */
509 int connect_to_stderr();
510
511 /**
512 * This constructor opens read and write file descriptors for the
513 * pipe. All the system calls made in its implementation are
514 * async-signal-safe.
515 * @param mode The mode in which the read file descriptor of the pipe
516 * is to be opened - either Cgu::PipeFifo::block or
517 * Cgu::PipeFifo::non_block.
518 * @exception Cgu::PipeError This exception is thrown if the opening
519 * of the pipe fails. No other exceptions will be thrown.
520 */
521 PipeFifo(Fifo_mode mode);
522
523 /**
524 * The default constructor does not open any descriptors. open() must
525 * be called before the PipeFifo object can be used. It is
526 * async-signal-safe. It does not throw.
527 */
528 PipeFifo();
529
530 /**
531 * The destructor does not throw. It is async-signal-safe.
532 */
533 ~PipeFifo() {close();}
534
535 /* Only has effect if --with-glib-memory-slices-compat or
536 * --with-glib-memory-slices-no-compat option picked */
537 CGU_GLIB_MEMORY_SLICES_FUNCS
538 };
539
540
541
542 /**
543 * @class SyncPipe pipes.h c++-gtk-utils/pipes.h
544 * @brief A class which uses an anonymous pipe to synchronise between
545 * processes.
546 * @sa PipeFifo
547 *
548 * This class enables synchronisation between processes after
549 * fork()ing. The process to wait on the other one calls wait() at
550 * the point where it wishes to wait, and the other process calls
551 * release() when it wants to enable the other process to continue.
552 * It is one-shot only - once it has released, it cannot re-block
553 * again. It is typically for use when a child process is setting
554 * itself up, or has a specific task to achieve, and needs to
555 * co-ordinate with the parent process or tell the parent process when
556 * it has done this. In such a case, the parent would wait until the
557 * child releases it.
558 */
559 class SyncPipe {
560 PipeFifo pipe_fifo;
561 public:
562 /**
563 * Releases another process waiting on this pipe. If the other
564 * process has not yet called wait(), when it does so wait() will
565 * immediately return. This may safely be called after a
566 * multi-threaded process forks() (all the system calls made in its
567 * implementation are async-signal-safe), but only one thread should
568 * call it. It does not throw.
569 */
570 void release() {pipe_fifo.make_writeonly(); pipe_fifo.make_readonly();}
571
572 /**
573 * Blocks until another process has called release() on this pipe. If
574 * the other process has already called release(), this function will
575 * immediately return. This may safely be called after a
576 * multi-threaded process forks() (all the system calls made in its
577 * implementation are async-signal-safe), but only one thread should
578 * call it. It does not throw.
579 */
580 void wait();
581
582 /**
583 * All the system calls made in the constructor are async-signal-safe.
584 * @exception Cgu::PipeError This exception is thrown if the opening
585 * of the pipe fails. No other exceptions will be thrown.
586 */
587 // using uniform initializer syntax here confuses doxygen
588 SyncPipe(): pipe_fifo(PipeFifo::block) {}
589
590 /**
591 * The destructor does not throw. It is async-signal-safe.
592 */
593 ~SyncPipe() {}
594
595 /* Only has effect if --with-glib-memory-slices-compat or
596 * --with-glib-memory-slices-no-compat option picked */
597 CGU_GLIB_MEMORY_SLICES_FUNCS
598 };
599
600 } // namespace Cgu
601
602 #endif