ian@0: //
ian@0: // Boost.Process
ian@0: // ~~~~~~~~~~~~~
ian@0: //
ian@0: // Copyright (c) 2006, 2007 Julio M. Merino Vidal
ian@0: // Copyright (c) 2008 Ilya Sokolov, Boris Schaeling
ian@0: // Copyright (c) 2009 Boris Schaeling
ian@0: // Copyright (c) 2010 Felipe Tanus, Boris Schaeling
ian@0: //
ian@0: // Distributed under the Boost Software License, Version 1.0. (See accompanying
ian@0: // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
ian@0: //
ian@0: 
ian@0: /**
ian@0:  * \file boost/process/pistream.hpp
ian@0:  *
ian@0:  * Includes the declaration of the pistream class.
ian@0:  */
ian@0: 
ian@0: #ifndef BOOST_PROCESS_PISTREAM_HPP
ian@0: #define BOOST_PROCESS_PISTREAM_HPP
ian@0: 
ian@0: #include <boost/process/handle.hpp>
ian@0: #include <boost/process/detail/systembuf.hpp>
ian@0: #include <boost/noncopyable.hpp>
ian@0: #include <istream>
ian@0: 
ian@0: namespace boost {
ian@0: namespace process {
ian@0: 
ian@0: /**
ian@0:  * Child process' output stream.
ian@0:  *
ian@0:  * The pistream class represents an output communication channel with the
ian@0:  * child process. The child process writes data to this stream and the
ian@0:  * parent process can read it through the pistream object. In other
ian@0:  * words, from the child's point of view, the communication channel is an
ian@0:  * output one, but from the parent's point of view it is an input one;
ian@0:  * hence the confusing pistream name.
ian@0:  *
ian@0:  * pistream objects cannot be copied because they buffer data
ian@0:  * that flows through the communication channel.
ian@0:  *
ian@0:  * A pistream object behaves as a std::istream stream in all senses.
ian@0:  * The class is only provided because it must provide a method to let
ian@0:  * the caller explicitly close the communication channel.
ian@0:  *
ian@0:  * \remark Blocking remarks: Functions that read data from this
ian@0:  *         stream can block if the associated handle blocks during
ian@0:  *         the read. As this class is used to communicate with child
ian@0:  *         processes through anonymous pipes, the most typical blocking
ian@0:  *         condition happens when the child has no more data to send to
ian@0:  *         the pipe's system buffer. When this happens, the buffer
ian@0:  *         eventually empties and the system blocks until the writer
ian@0:  *         generates some data.
ian@0:  */
ian@0: class pistream : public std::istream, public boost::noncopyable
ian@0: {
ian@0: public:
ian@0:     /**
ian@0:      * Creates a new process' output stream.
ian@0:      */
ian@0:     explicit pistream(boost::process::handle h)
ian@0:         : std::istream(0),
ian@0:           handle_(h),
ian@0:           systembuf_(handle_.native())
ian@0:     {
ian@0:         rdbuf(&systembuf_);
ian@0:     }
ian@0: 
ian@0:     /**
ian@0:      * Returns the handle managed by this stream.
ian@0:      */
ian@0:     const boost::process::handle &handle() const
ian@0:     {
ian@0:         return handle_;
ian@0:     }
ian@0: 
ian@0:     /**
ian@0:      * Returns the handle managed by this stream.
ian@0:      */
ian@0:     boost::process::handle &handle()
ian@0:     {
ian@0:         return handle_;
ian@0:     }
ian@0: 
ian@0:     /**
ian@0:      * Closes the handle managed by this stream.
ian@0:      *
ian@0:      * Explicitly closes the handle managed by this stream. This
ian@0:      * function can be used by the user to tell the child process it's
ian@0:      * not willing to receive more data.
ian@0:      */
ian@0:     void close()
ian@0:     {
ian@0:         handle_.close();
ian@0:     }
ian@0: 
ian@0: private:
ian@0:     /**
ian@0:      * The handle managed by this stream.
ian@0:      */
ian@0:     boost::process::handle handle_;
ian@0: 
ian@0:     /**
ian@0:      * The systembuf object used to manage this stream's data.
ian@0:      */
ian@0:     detail::systembuf systembuf_;
ian@0: };
ian@0: 
ian@0: }
ian@0: }
ian@0: 
ian@0: #endif