c++-gtk-utils
pipes.h
Go to the documentation of this file.
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