c++-gtk-utils
|
00001 /* Copyright (C) 1999 to 2004, and 2009 to 2011 Chris Vine 00002 00003 The library comprised in this file or of which this file is part is 00004 distributed by Chris Vine under the GNU Lesser General Public 00005 License as follows: 00006 00007 This library is free software; you can redistribute it and/or 00008 modify it under the terms of the GNU Lesser General Public License 00009 as published by the Free Software Foundation; either version 2.1 of 00010 the License, or (at your option) any later version. 00011 00012 This library is distributed in the hope that it will be useful, but 00013 WITHOUT ANY WARRANTY; without even the implied warranty of 00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00015 Lesser General Public License, version 2.1, for more details. 00016 00017 You should have received a copy of the GNU Lesser General Public 00018 License, version 2.1, along with this library (see the file LGPL.TXT 00019 which came with this source code package in the c++-gtk-utils 00020 sub-directory); if not, write to the Free Software Foundation, Inc., 00021 59 Temple Place - Suite 330, Boston, MA, 02111-1307, USA. 00022 00023 */ 00024 00025 #ifndef CGU_PIPES_H 00026 #define CGU_PIPES_H 00027 00028 #include <unistd.h> 00029 00030 #include <exception> 00031 00032 #include <c++-gtk-utils/cgu_config.h> 00033 00034 namespace Cgu { 00035 00036 /** 00037 * @class PipeFifo pipes.h c++-gtk-utils/pipes.h 00038 * @brief A wrapper for unix anonymous pipes. 00039 * @sa SyncPipe 00040 * 00041 * This class provides a simplified front end for anonymous fifo pipes 00042 * (as created by the pipe() system call). The constructor of the 00043 * class may be passed an enumerator to indicate whether the pipe is 00044 * to read in non-blocking mode. 00045 * 00046 * With the write(const char*, int) method, taking an array and int 00047 * arguments, the value of int (indicating the number of chars in the 00048 * array to be written) should usually be less than PIPE_BUF, as POSIX 00049 * write() guarantees that if it is less than PIPE_BUF, either all 00050 * will be written or, if the pipe is too full, none will be written. 00051 * This prevents data interleaving if a number of independent writes 00052 * to the fifo are made. The same is true of the write (const char*) 00053 * method taking a string - if the string is longer than PIPE_BUF in 00054 * size, data interleaving may occur. 00055 * 00056 * The pipe is set to read in non-blocking mode if the constructor of 00057 * PipeFifo, or PipeFifo::open(), is passed the value 00058 * PipeFifo::non_block. If constructed in this way, the pipe can also 00059 * be set to write in non-block mode (eg to minimise the impact on 00060 * another program running in a child process to which the child 00061 * process has exec()ed when monitoring its stdin or stderr) by 00062 * calling make_write_non_block(). However use this very sparingly -- 00063 * when set in this way write() will always try to write something. 00064 * The atomic guarantees mentioned in the preceding paragraph do not 00065 * apply and data can be interleaved or lost. 00066 * 00067 * PIPE_BUF is defined in limits.h, and is at least 512 bytes, and 00068 * usually 4096 bytes, but may be calculated from other files included 00069 * by limits.h. 00070 * 00071 * Where a pipe is used to communicate between parent and child after 00072 * a call to fork(), the pipe will normally be used unidirectionally 00073 * unless guards or semaphores are used to prevent a process reading 00074 * data intended for the other. However, because each process 00075 * inherits its own duplicate of the file descriptors, this cannot be 00076 * enforced without closing the read or write file descriptor for the 00077 * process for which the reading or writing is to be prohibited. This 00078 * can be done by the process concerned calling the methods 00079 * PipeFifo::make_writeonly() or PipeFifo::make_readonly() after the 00080 * fork. If an attempt is made to read or write to a descriptor 00081 * closed in this way, the PipeFifo::read() or PipeFifo::write() 00082 * method will ensure that no read or write will take place, and 00083 * instead -2 will be returned. 00084 * 00085 * The methods PipeFifo::connect_to_stdin(), 00086 * PipeFifo::connect_to_stdout() and PipeFifo::connect_to_stderr() are 00087 * available to be used in the child process before it exec()s another 00088 * program so as to connect the pipe to that program's stdin, stdout 00089 * or stderr. PipeFifo::connect_to_stdin() cannot be used by a 00090 * process after that process has called PipeFifo::make_writeonly(), 00091 * and PipeFifo::connect_to_stdout() and PipeFifo::connect_to_stderr() 00092 * cannot be used after the process has called 00093 * PipeFifo::make_readonly(), nor can a pipe in any one process be 00094 * connected to more than one of stdin, stdout or stderr. If that is 00095 * attempted the methods will return -2. Furthermore, they should 00096 * only be used after the process creating the pipe has forked. If 00097 * the connection to stdin, stdout or stderr is to be made before the 00098 * fork, this must be done by hand using dup2(), 00099 * PipeFifo::get_write_fd()/ PipeFifo::get_read_fd() and 00100 * PipeFifo::make_read_only()/ PipeFifo::make_write_only(). 00101 * 00102 * If PipeFifo::connect_to_stdin() is called by a method, 00103 * PipeFifo::make_readonly() will also be called, and if 00104 * PipeFifo::connect_to_stdout() or PipeFifo::connect_to_stderr() are 00105 * called, PipeFifo::make_writeonly() will also be called. This will 00106 * isolate the use of the pipe by the child process to stdin, stdout 00107 * or stderr, as appropriate. 00108 * 00109 * It uses no static members, so is thread safe as between different 00110 * objects, but its methods are not thread safe as regards any one 00111 * object in the sense that the read() and write() methods check the 00112 * value of read_fd and write_fd respectively (and get_read_fd() and 00113 * get_write_fd() return them), and make_writeonly(), make_readonly(), 00114 * close(), connect_to_stdin(), open(), connect_to_stdout() and 00115 * connect_to_stderr() change those values. Likewise the read() and 00116 * write() methods access read_blocking_mode and write_blocking_mode 00117 * respectively, and these are changed by open() and 00118 * make_write_non_block(). Provided there is no concurrent use of 00119 * read(), write(), get_read_fd() or get_write_fd() in one thread with 00120 * a call of a method which changes read_fd, write_fd, 00121 * read_blocking_mode or write_blocking_mode as described above in 00122 * another thread then no mutex is required to ensure thread safety. 00123 * 00124 * All the read() and write() methods check for an interruption of the 00125 * system call from a signal (EINTR is checked), and will continue to 00126 * read() or write() where necessary. Users do not need to check 00127 * EINTR themselves. Where the write file descriptor is flagged as 00128 * blocking (that is, where PipeFifo::make_write_non_block() has not 00129 * been called), then in the absence of some other error, everything 00130 * passed to PipeFifo::write() will be written (but as mentioned above 00131 * there may be data interleaving if this is greater than PIPE_BUF in 00132 * size). Where the write file descriptor is flagged as non-blocking, 00133 * then the result of Unix write is returned, and less bytes than 00134 * those passed to PipeFifo::write() may have been written, or -1 may 00135 * be returned with errno set to EAGAIN - it is for the user to check 00136 * this. 00137 * 00138 * If you are using pipes to write and read between processes, you 00139 * will probably want to call sigaction() to cause the SIGPIPE signal 00140 * to be ignored. SIGPIPE has little use in most programming: if 00141 * SIGPIPE is ignored, and an attempt is made to write to a pipe which 00142 * has been closed at the read end, then the write will return -1 and 00143 * errno will be set to EPIPE. 00144 */ 00145 00146 struct PipeError: public std::exception { 00147 virtual const char* what() const throw() {return "PipeError: error opening pipe\n";} 00148 }; 00149 00150 class PipeFifo { 00151 public: 00152 enum Fifo_mode{block, non_block}; 00153 private: 00154 int read_fd; 00155 int write_fd; 00156 Fifo_mode read_blocking_mode; 00157 Fifo_mode write_blocking_mode; 00158 00159 public: 00160 /** 00161 * This class cannot be copied. The copy constructor is deleted. 00162 */ 00163 PipeFifo(const PipeFifo&) = delete; 00164 00165 /** 00166 * This class cannot be copied. The assignment operator is deleted. 00167 */ 00168 PipeFifo& operator=(const PipeFifo&) = delete; 00169 00170 /** 00171 * Opens read and write file descriptors for the pipe. If the pipe is 00172 * already open, it will close the existing file descriptors. This 00173 * function call is thread-safe to the extent that all the system 00174 * calls made in its implementation are async-signal-safe, so it may 00175 * safely be called in a multi-threaded program after a fork() and 00176 * before an exec(). However, the manipulation of the file 00177 * descriptors and related variables is not protected by a mutex, so 00178 * if different threads in the same process are to manipulate the same 00179 * pipe object with this method, close(), connect_to_stdin(), 00180 * connect_to_stdout() or connect_to_stderr() (which manipulate both 00181 * descriptors), make_readonly() or make_write_non_block() (which 00182 * manipulate the write file descriptor), or make_writeonly() (which 00183 * manipulates the read file descriptor), or read the value of the 00184 * file descriptor with get_read_fd() or read() (which access the read 00185 * file descriptor) or get_write_fd() or write() (which access the 00186 * write file descriptor) concurrently with such a manipulation, then 00187 * the user should provide appropriate synchronisation. 00188 * @param mode The mode in which the read file descriptor of the pipe 00189 * is to be opened - either Cgu::PipeFifo::block or 00190 * Cgu::PipeFifo::non_block. 00191 * @exception Cgu::PipeError This exception is thrown if the opening 00192 * of the pipe fails. No other exceptions will be thrown. 00193 */ 00194 void open(Fifo_mode mode); 00195 00196 /** 00197 * Closes the read and write file descriptors of the pipe (if they are 00198 * open). This function call is thread-safe to the extent that all 00199 * the system calls made in its implementation are async-signal-safe, 00200 * so it may safely be called in a multi-threaded program after a 00201 * fork() and before an exec(). However, the manipulation of the file 00202 * descriptors and related variables is not protected by a mutex, so 00203 * if different threads in the same process are to manipulate the same 00204 * pipe object with this method, open(), connect_to_stdin(), 00205 * connect_to_stdout() or connect_to_stderr() (which manipulate both 00206 * descriptors), make_readonly() or make_write_non_block() (which 00207 * manipulate the write file descriptor), or make_writeonly() (which 00208 * manipulates the read file descriptor), or read the value of the 00209 * file descriptor with get_read_fd() or read() (which access the read 00210 * file descriptor) or get_write_fd() or write() (which access the 00211 * write file descriptor) concurrently with such a manipulation, then 00212 * the user should provide appropriate synchronisation. No exceptions 00213 * will be thrown. 00214 */ 00215 void close(); 00216 00217 /** 00218 * Reads up to max_num characters from the pipe. This read does not 00219 * carry on blocking until the read request is met: unless there is an 00220 * interrupt, it just calls POSIX read() once and takes what is 00221 * available. If a specific number of characters is required, the 00222 * user should provide an appropriate do/while loop. It does not 00223 * throw. Any reasonable POSIX implementation will do an atomic read 00224 * as between threads if max_num is PIPE_BUF or less in size, but the 00225 * POSIX standard only requires such atomic reads as between processes 00226 * rather than as between threads. The user does not need to check 00227 * for EINTR and an interrupt: this method deals with that 00228 * automatically. All the system calls made in its implementation are 00229 * async-signal-safe, and it is re-entrant subject to errno being 00230 * saved. This method does not throw. 00231 * @param buf A buffer into which the characters will be placed. 00232 * @param max_num The maximum number of characters to be read 00233 * (normally the size of the buffer). 00234 * @return -2 if the read file descriptor is invalid, otherwise the 00235 * result of unix read() - that is, the number of characters read, or 00236 * 0 if end of file is reached (ie the write descriptor has been 00237 * closed), or -1 if there has been an error (but EINTR never returns 00238 * as an error as the implementation handles that). In the event of 00239 * an error, errno is set. 00240 */ 00241 ssize_t read(char* buf, size_t max_num); 00242 00243 /** 00244 * Extracts a character from the pipe. This method does not throw. 00245 * All the system calls made in its implementation are 00246 * async-signal-safe and it is re-entrant subject to errno being 00247 * saved. It is thread safe. 00248 * @return The character at the front of the pipe if available, 00249 * otherwise -2 if the read file descriptor is invalid, 0 if end of 00250 * file is reached (ie the write descriptor has been closed), or -1 if 00251 * there has been an error (but EINTR never returns as an error as the 00252 * implementation handles that). In the event of an error, errno is 00253 * set. 00254 */ 00255 int read(); 00256 00257 /** 00258 * Write a NUL terminated C string to the pipe, excluding the 00259 * terminating NUL character. If the write file descriptor is set as 00260 * blocking (the default) then this method will carry on blocking 00261 * until everything is sent, even if it exceeds PIPE_BUF in size. Any 00262 * reasonable POSIX implementation will do an atomic write (with no 00263 * interleaving) as between threads if the number of characters in the 00264 * string is PIPE_BUF or less in size, but the POSIX standard only 00265 * requires such atomic writes as between processes rather than as 00266 * between threads. All the system calls made in its implementation 00267 * are async-signal-safe and it is re-entrant subject to errno being 00268 * saved. This method does not throw. 00269 * @param str The string to be written. 00270 * @return -2 if write file descriptor invalid, otherwise it returns 00271 * the number of bytes written or -1 if there has been an error (but 00272 * EINTR never returns as an error as the implementation handles 00273 * that). In the event of an error, errno is set. 00274 */ 00275 ssize_t write(const char* str); 00276 00277 /** 00278 * Write a buffer of characters to the pipe. If the write file 00279 * descriptor is set as blocking (the default) then this method will 00280 * carry on blocking until everything is sent, even if it exceeds 00281 * PIPE_BUF in size. Any reasonable POSIX implementation will do an 00282 * atomic write (with no interleaving) as between threads if num is 00283 * PIPE_BUF or less in size, but the POSIX standard only requires such 00284 * atomic writes as between processes rather than as between threads. 00285 * All the system calls made in its implementation are 00286 * async-signal-safe and it is re-entrant subject to errno being 00287 * saved. This method does not throw. 00288 * @param buf The buffer to be written. 00289 * @param num The number of characters in the buffer. 00290 * @return -2 if write file descriptor invalid, otherwise it returns 00291 * the number of bytes written or -1 if there has been an error (but 00292 * EINTR never returns as an error as the implementation handles 00293 * that). In the event of an error, errno is set. 00294 */ 00295 ssize_t write(const char* buf, size_t num); 00296 00297 /** 00298 * Write a character to the pipe. All the system calls made in its 00299 * implementation are async-signal-safe and it is re-entrant subject 00300 * to errno being saved. This method does not throw. It is thread 00301 * safe. 00302 * @param item The character to be written. 00303 * @return 1 if the character was written, -2 if the write file 00304 * descriptor is invalid, or -1 if there has been an error (but EINTR 00305 * never returns as an error as the implementation handles that). In 00306 * the event of an error, errno is set. 00307 */ 00308 int write(char item) {return write(&item, 1);} 00309 00310 /** 00311 * Make the pipe only available for writing in the calling process, by 00312 * closing the read file descriptor. This function call is thread 00313 * safe to the extent that all the system calls made in its 00314 * implementation are async-signal-safe, so it may safely be called in 00315 * a multi-threaded program after a fork() and before an exec(). 00316 * However, the manipulation of the file descriptor and related 00317 * variables is not protected by a mutex, so if different threads in 00318 * the same process are to manipulate the same pipe object with 00319 * open(), close(), connect_to_stdin(), connect_to_stdout() or 00320 * connect_to_stderr() (which manipulate both descriptors), or this 00321 * method (which manipulates the read file descriptor), or read the 00322 * value of the read file descriptor with get_read_fd() or read() 00323 * concurrently with such a manipulation, then the user should provide 00324 * appropriate synchronisation. No exceptions will be thrown. 00325 */ 00326 void make_writeonly(); 00327 00328 /** 00329 * Make the pipe only available for reading in the calling process, by 00330 * closing the write file descriptor. This function call is 00331 * thread-safe to the extent that all the system calls made in its 00332 * implementation are async-signal-safe, so it may safely be called in 00333 * a multi-threaded program after a fork() and before an exec(). 00334 * However, the manipulation of the file descriptor and related 00335 * variables is not protected by a mutex, so if different threads in 00336 * the same process are to manipulate the same pipe object with 00337 * open(), close(), connect_to_stdin(), connect_to_stdout() or 00338 * connect_to_stderr() (which manipulate both descriptors), or this 00339 * method or make_write_non_block() (which manipulate the write file 00340 * descriptor), or read the value of the write file descriptor with 00341 * get_write_fd() or write() concurrently with such a manipulation, 00342 * then the user should provide appropriate synchronisation. No 00343 * exceptions will be thrown. 00344 */ 00345 void make_readonly(); 00346 00347 /** 00348 * Makes the write file descriptor non-blocking. This is only very 00349 * rarely needed. If the write file descriptor is set non-blocking, 00350 * then there are no atomic write guarantees. This function call is 00351 * thread safe to the extent that all the system calls made in its 00352 * implementation are async-signal-safe, so it may safely be called in 00353 * a multi-threaded program after a fork() and before an exec(). 00354 * However, the manipulation of the file descriptor and related 00355 * variables is not protected by a mutex, so if different threads in 00356 * the same process are to manipulate the same pipe object with 00357 * open(), close(), connect_to_stdin(), connect_to_stdout() or 00358 * connect_to_stderr() (which manipulate both descriptors), or this 00359 * method or make_readonly() (which manipulate the write file 00360 * descriptor), or read the value of the write file descriptor with 00361 * get_write_fd() or write() concurrently with such a manipulation, 00362 * then the user should provide appropriate synchronisation. No 00363 * exceptions will be thrown. 00364 * @return 0 if the write file descriptor is open, or -1 otherwise. 00365 */ 00366 int make_write_non_block(); 00367 00368 /** 00369 * Get the read file descriptor (if any). The fetching of the file 00370 * descriptor is not protected by a mutex, so if different threads in 00371 * the same process are to manipulate the same pipe object with 00372 * open(), close(), connect_to_stdin(), connect_to_stdout() or 00373 * connect_to_stderr() (which manipulate both descriptors), or 00374 * make_writeonly() (which manipulates the read file descriptor), or 00375 * read the value of the file descriptor with this method or read() 00376 * concurrently with such a manipulation, then the user should provide 00377 * appropriate synchronisation. No exceptions will be thrown. 00378 * @return The read file descriptor, or -1 is none is open. 00379 */ 00380 int get_read_fd() const {return read_fd;} 00381 00382 /** 00383 * Get the write file descriptor (if any). The fetching of the file 00384 * descriptor is not protected by a mutex, so if different threads in 00385 * the same process are to manipulate the same pipe object with 00386 * open(), close(), connect_to_stdin(), connect_to_stdout() or 00387 * connect_to_stderr() (which manipulate both descriptors), or 00388 * make_readonly() or make_write_non_block() (which manipulate the 00389 * write file descriptor), or read the value of the file descriptor 00390 * with this method or write() concurrently with such a manipulation, 00391 * then the user should provide appropriate synchronisation. No 00392 * exceptions will be thrown. 00393 * @return The write file descriptor, or -1 is none is open. 00394 */ 00395 int get_write_fd() const {return write_fd;} 00396 00397 /** 00398 * Connect the read file descriptor of the pipe to stdin. Once 00399 * called, any read from stdin in the process which calls this method 00400 * will be read from the pipe. It should only be called in a child 00401 * process or parent process after a fork() where the PipeFifo object 00402 * has been created in the parent process, and typically is called by 00403 * the child process before one of the exec() functions is invoked by 00404 * the child process. It should only be called once, and cannot be 00405 * called after connect_to_stdout(), connect_to_stderr() or 00406 * make_writeonly() has been called in the same process. Once called, 00407 * the write file descriptor is no longer available to the process 00408 * calling this method. Typically it would be used in order that when 00409 * the new process image created by exec() reads from stdin, it reads 00410 * from the pipe, and the parent process (or another child process) 00411 * writes to the pipe. This function call is thread safe to the 00412 * extent that all the system calls made in its implementation are 00413 * async-signal-safe, so it may safely be called in a multi-threaded 00414 * program after a fork() and before an exec(). However, the 00415 * manipulation of the file descriptors and related variables is not 00416 * protected by a mutex, so if different threads in the same process 00417 * are to manipulate the same pipe object with this method, open(), 00418 * close(), connect_to_stdout() or connect_to_stderr() (which 00419 * manipulate both descriptors), make_readonly() or 00420 * make_write_non_block() (which manipulate the write file 00421 * descriptor), or make_writeonly() (which manipulates the read file 00422 * descriptor), or read the value of the file descriptor with 00423 * get_read_fd() or read() (which access the read file descriptor) or 00424 * get_write_fd() or write() (which access the write file descriptor) 00425 * concurrently with such a manipulation, then the user should provide 00426 * appropriate synchronisation. It does not throw. 00427 * @return -2 if the read file descriptor has previously been closed 00428 * or this method, connect_to_stdout() or connect_to_stderr() has 00429 * previously been called in the same process, otherwise it returns 00430 * the value returned by dup2(), that is 0 if the operation succeeds, 00431 * or -1 (with errno set) if not. It does not throw. 00432 */ 00433 int connect_to_stdin(); 00434 00435 /** 00436 * Connect the write file descriptor of the pipe to stdout. Once 00437 * called, any write to stdout in the process which calls this method 00438 * will be written to the pipe. It should only be called in a child 00439 * or parent process after a fork() where the PipeFifo object has been 00440 * created in the parent process, and typically is called by the child 00441 * process before one of the exec() functions is invoked by the child 00442 * process. It should only be called once, and cannot be called after 00443 * connect_to_stdin(), connect_to_stderr() or make_readonly() has been 00444 * called in the same process. Once called, the read file descriptor 00445 * is no longer available to the process calling this method. 00446 * Typically it would be used in order that when the new process image 00447 * created by exec() writes to stdout, it writes to the pipe, and the 00448 * parent process (or another child process) reads from the pipe. 00449 * This function call is thread safe to the extent that all the system 00450 * calls made in its implementation are async-signal-safe, so it may 00451 * safely be called in a multi-threaded program after a fork() and 00452 * before an exec(). However, the manipulation of the file 00453 * descriptors and related variables is not protected by a mutex, so 00454 * if different threads in the same process are to manipulate the same 00455 * pipe object with this method, open(), close(), connect_to_stdin() 00456 * or connect_to_stderr() (which manipulate both descriptors), 00457 * make_readonly() or make_write_non_block() (which manipulate the 00458 * write file descriptor), or make_writeonly() (which manipulates the 00459 * read file descriptor), or read the value of the file descriptor 00460 * with get_read_fd() or read() (which access the read file 00461 * descriptor) or get_write_fd() or write() (which access the write 00462 * file descriptor) concurrently with such a manipulation, then the 00463 * user should provide appropriate synchronisation. It does not 00464 * throw. 00465 * @return -2 if the write file descriptor has previously been closed 00466 * or this method, connect_to_stdin() or connect_to_stderr() has 00467 * previously been called in the same process, otherwise it returns 00468 * the value returned by dup2(), that is 0 if the operation succeeds, 00469 * or -1 (with errno set) if not. It does not throw. 00470 */ 00471 int connect_to_stdout(); 00472 00473 /** 00474 * Connect the write file descriptor of the pipe to stderr. Once 00475 * called, any write to stderr in the process which calls this method 00476 * will be written to the pipe. It should only be called in a child 00477 * or parent process after a fork() where the PipeFifo object has been 00478 * created in the parent process, and typically is called by a child 00479 * process before one of the exec() functions is invoked by the child 00480 * process. It should only be called once, and cannot be called after 00481 * connect_to_stdin(), connect_to_stdout() or make_readonly() has been 00482 * called in the same process. Once called, the read file descriptor 00483 * is no longer available to the process calling this method. 00484 * Typically it would be used in order that when the new process image 00485 * created by exec() writes to stderr, it writes to the pipe, and the 00486 * parent process (or another child process) reads from the pipe. 00487 * This function call is thread safe to the extent that all the system 00488 * calls made in its implementation are async-signal-safe, so it may 00489 * safely be called in a multi-threaded program after a fork() and 00490 * before an exec(). However, the manipulation of the file 00491 * descriptors and related variables is not protected by a mutex, so 00492 * if different threads in the same process are to manipulate the same 00493 * pipe object with this method, open(), close(), connect_to_stdin() 00494 * or connect_to_stdout() (which manipulate both descriptors), 00495 * make_readonly() or make_write_non_block() (which manipulate the 00496 * write file descriptor), or make_writeonly() (which manipulates the 00497 * read file descriptor), or read the value of the file descriptor 00498 * with get_read_fd() or read() (which access the read file 00499 * descriptor) or get_write_fd() or write() (which access the write 00500 * file descriptor) concurrently with such a manipulation, then the 00501 * user should provide appropriate synchronisation. It does not 00502 * throw. 00503 * @return -2 if the write file descriptor has previously been closed 00504 * or this method, connect_to_stdin() or connect_to_stdout() has 00505 * previously been called in the same process, otherwise it returns 00506 * the value returned by dup2(), that is 0 if the operation succeeds, 00507 * or -1 (with errno set) if not. It does not throw. 00508 */ 00509 int connect_to_stderr(); 00510 00511 /** 00512 * This constructor opens read and write file descriptors for the 00513 * pipe. All the system calls made in its implementation are 00514 * async-signal-safe. 00515 * @param mode The mode in which the read file descriptor of the pipe 00516 * is to be opened - either Cgu::PipeFifo::block or 00517 * Cgu::PipeFifo::non_block. 00518 * @exception Cgu::PipeError This exception is thrown if the opening 00519 * of the pipe fails. No other exceptions will be thrown. 00520 */ 00521 PipeFifo(Fifo_mode mode); 00522 00523 /** 00524 * The default constructor does not open any descriptors. open() must 00525 * be called before the PipeFifo object can be used. It is 00526 * async-signal-safe. It does not throw. 00527 */ 00528 PipeFifo(); 00529 00530 /** 00531 * The destructor does not throw. It is async-signal-safe. 00532 */ 00533 ~PipeFifo() {close();} 00534 00535 /* Only has effect if --with-glib-memory-slices-compat or 00536 * --with-glib-memory-slices-no-compat option picked */ 00537 CGU_GLIB_MEMORY_SLICES_FUNCS 00538 }; 00539 00540 00541 00542 /** 00543 * @class SyncPipe pipes.h c++-gtk-utils/pipes.h 00544 * @brief A class which uses an anonymous pipe to synchronise between 00545 * processes. 00546 * @sa PipeFifo 00547 * 00548 * This class enables synchronisation between processes after 00549 * fork()ing. The process to wait on the other one calls wait() at 00550 * the point where it wishes to wait, and the other process calls 00551 * release() when it wants to enable the other process to continue. 00552 * It is one-shot only - once it has released, it cannot re-block 00553 * again. It is typically for use when a child process is setting 00554 * itself up, or has a specific task to achieve, and needs to 00555 * co-ordinate with the parent process or tell the parent process when 00556 * it has done this. In such a case, the parent would wait until the 00557 * child releases it. 00558 */ 00559 class SyncPipe { 00560 PipeFifo pipe_fifo; 00561 public: 00562 /** 00563 * Releases another process waiting on this pipe. If the other 00564 * process has not yet called wait(), when it does so wait() will 00565 * immediately return. This may safely be called after a 00566 * multi-threaded process forks() (all the system calls made in its 00567 * implementation are async-signal-safe), but only one thread should 00568 * call it. It does not throw. 00569 */ 00570 void release() {pipe_fifo.make_writeonly(); pipe_fifo.make_readonly();} 00571 00572 /** 00573 * Blocks until another process has called release() on this pipe. If 00574 * the other process has already called release(), this function will 00575 * immediately return. This may safely be called after a 00576 * multi-threaded process forks() (all the system calls made in its 00577 * implementation are async-signal-safe), but only one thread should 00578 * call it. It does not throw. 00579 */ 00580 void wait(); 00581 00582 /** 00583 * All the system calls made in the constructor are async-signal-safe. 00584 * @exception Cgu::PipeError This exception is thrown if the opening 00585 * of the pipe fails. No other exceptions will be thrown. 00586 */ 00587 // using uniform initializer syntax here confuses doxygen 00588 SyncPipe(): pipe_fifo(PipeFifo::block) {} 00589 00590 /** 00591 * The destructor does not throw. It is async-signal-safe. 00592 */ 00593 ~SyncPipe() {} 00594 00595 /* Only has effect if --with-glib-memory-slices-compat or 00596 * --with-glib-memory-slices-no-compat option picked */ 00597 CGU_GLIB_MEMORY_SLICES_FUNCS 00598 }; 00599 00600 } // namespace Cgu 00601 00602 #endif