boost/process/async_pipe.hpp

0001 // Copyright (c) 2006, 2007 Julio M. Merino Vidal
0002 // Copyright (c) 2008 Ilya Sokolov, Boris Schaeling
0003 // Copyright (c) 2009 Boris Schaeling
0004 // Copyright (c) 2010 Felipe Tanus, Boris Schaeling
0005 // Copyright (c) 2011, 2012 Jeff Flinn, Boris Schaeling
0006 //
0007 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0008 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0009
0010
0011 #ifndef BOOST_PROCESS_ASYNC_PIPE_HPP
0012 #define BOOST_PROCESS_ASYNC_PIPE_HPP
0013
0014 #include <boost/config.hpp>
0015 #include <boost/process/detail/config.hpp>
0016
0017 #if defined(BOOST_POSIX_API)
0018 #include <boost/process/detail/posix/async_pipe.hpp>
0019 #elif defined(BOOST_WINDOWS_API)
0020 #include <boost/process/detail/windows/async_pipe.hpp>
0021 #endif
0022
0023 namespace boost { namespace process {
0024
0025
0026 #if defined(BOOST_PROCESS_DOXYGEN)
0027
0028
0029 /** Class implementing an asnychronous I/O-Object for use with boost.asio.
0030  *  It is based on the corresponding I/O Object, that is either boost::asio::windows::stream_handle or
0031  *  boost::asio::posix::stream_descriptor.
0032  *
0033  *  It can be used directly with boost::asio::async_read or async_write.
0034  *
0035  * \note The object is copyable, but that does invoke a handle duplicate.
0036  */
0037 class async_pipe
0038 {
0039 public:
0040     /** Typedef for the native handle representation.
0041      * \note This is the handle on the system, not the boost.asio class.
0042      *
0043      */
0044     typedef platform_specific native_handle_type;
0045     /** Typedef for the handle representation of boost.asio.
0046      *
0047      */
0048     typedef platform_specific handle_type;
0049
0050     typedef typename handle_type::executor_type executor_type;
0051
0052     /** Construct a new async_pipe, does automatically open the pipe.
0053      * Initializes source and sink with the same io_context.
0054      * @note Windows creates a named pipe here, where the name is automatically generated.
0055      */
0056     inline async_pipe(boost::asio::io_context & ios);
0057
0058     /** Construct a new async_pipe, does automatically open the pipe.
0059      * @note Windows creates a named pipe here, where the name is automatically generated.
0060      */
0061     inline async_pipe(boost::asio::io_context & ios_source,
0062                       boost::asio::io_context & ios_sink);
0063
0064     /** Construct a new async_pipe, does automatically open.
0065      * Initializes source and sink with the same io_context.
0066      *
0067      * @note Windows restricts possible names.
0068      */
0069     inline async_pipe(boost::asio::io_context & ios, const std::string & name);
0070
0071
0072     /** Construct a new async_pipe, does automatically open.
0073      *
0074      * @note Windows restricts possible names.
0075      */
0076     inline async_pipe(boost::asio::io_context & ios_source,
0077                       boost::asio::io_context & ios_sink, const std::string & name);
0078
0079     /** Copy-Constructor of the async pipe.
0080      * @note Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.
0081      *
0082      */
0083     async_pipe(const async_pipe& lhs);
0084
0085     /** Move-Constructor of the async pipe.
0086      */
0087     async_pipe(async_pipe&& lhs);
0088
0089     /** Construct the async-pipe from a pipe.
0090      * @note Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.
0091      *
0092      */
0093     template<class CharT, class Traits = std::char_traits<CharT>>
0094     explicit async_pipe(boost::asio::io_context & ios, const basic_pipe<CharT, Traits> & p);
0095
0096     /** Construct the async-pipe from a pipe, with two different io_context objects.
0097      * @note Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.
0098      *
0099      */
0100     template<class CharT, class Traits = std::char_traits<CharT>>
0101     explicit async_pipe(boost::asio::io_context & ios_source,
0102                         boost::asio::io_context & ios_sink,
0103                         const basic_pipe<CharT, Traits> & p);
0104
0105
0106     /** Assign a basic_pipe.
0107      * @note Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.
0108      *
0109      */
0110     template<class CharT, class Traits = std::char_traits<CharT>>
0111     inline async_pipe& operator=(const basic_pipe<CharT, Traits>& p);
0112
0113     /** Copy Assign a pipe.
0114      * @note Duplicates the handles.
0115      */
0116     async_pipe& operator=(const async_pipe& lhs);
0117     /** Move assign a pipe */
0118     async_pipe& operator=(async_pipe&& lhs);
0119
0120     /** Destructor. Closes the pipe handles. */
0121     ~async_pipe();
0122
0123     /** Explicit cast to basic_pipe.  */
0124     template<class CharT, class Traits = std::char_traits<CharT>>
0125     inline explicit operator basic_pipe<CharT, Traits>() const;
0126
0127     /** Cancel the current asynchronous operations. */
0128     void cancel();
0129     /** Close the pipe handles. */
0130     void close();
0131     /** Close the pipe handles. While passing an error_code
0132      *
0133      */
0134     void close(std::error_code & ec);
0135
0136     /** Check if the pipes are open. */
0137     bool is_open() const;
0138
0139     /** Async close, i.e. close after current operation is completed.
0140      *
0141      *  \note There is no guarantee that this will indeed read the entire pipe-buffer
0142      */
0143     void async_close();
0144
0145     /** Read some data from the handle.
0146
0147      * See the boost.asio documentation for more details.
0148      */
0149     template<typename MutableBufferSequence>
0150     std::size_t read_some(const MutableBufferSequence & buffers);
0151
0152     /** Write some data to the handle.
0153
0154      * See the boost.asio documentation for more details.
0155      */
0156     template<typename MutableBufferSequence>
0157     std::size_t write_some(const MutableBufferSequence & buffers);
0158
0159     /** Get the native handle of the source. */
0160     native_handle native_source() const {return const_cast<boost::asio::windows::stream_handle&>(_source).native();}
0161     /** Get the native handle of the sink. */
0162     native_handle native_sink  () const {return const_cast<boost::asio::windows::stream_handle&>(_sink  ).native();}
0163
0164     /** Start an asynchronous read.
0165      *
0166      * See the [boost.asio documentation](http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncReadStream.html) for more details.
0167      */
0168     template<typename MutableBufferSequence,
0169              typename ReadHandler>
0170     detail::dummy async_read_some(
0171         const MutableBufferSequence & buffers,
0172               ReadHandler &&handler);
0173
0174     /** Start an asynchronous write.
0175
0176      * See the [boost.asio documentation](http://www.boost.org/doc/libs/1_60_0/doc/html/boost_asio/reference/AsyncWriteStream.html) for more details.
0177      */
0178     template<typename ConstBufferSequence,
0179              typename WriteHandler>
0180     detail::dummy async_write_some(
0181         const ConstBufferSequence & buffers,
0182         WriteHandler && handler);
0183
0184     ///Get the asio handle of the pipe sink.
0185     const handle_type & sink  () const &;
0186     ///Get the asio handle of the pipe source.
0187     const handle_type & source() const &;
0188
0189     ///Get the asio handle of the pipe sink. Qualified as rvalue
0190     handle_type && sink  () &&;
0191     ///Get the asio handle of the pipe source. Qualified as rvalue
0192     handle_type && source() &&;
0193
0194     /// Move the source out of this class and change the io_context. Qualified as rvalue. \attention Will always move.
0195     handle_type source(::boost::asio::io_context& ios) &&;
0196     /// Move the sink out of this class and change the io_context. Qualified as rvalue. \attention Will always move
0197     handle_type sink  (::boost::asio::io_context& ios) &&;
0198
0199     /// Copy the source out of this class and change the io_context. \attention Will always copy.
0200     handle_type source(::boost::asio::io_context& ios) const &;
0201     /// Copy the sink out of this class and change the io_context. \attention Will always copy
0202     handle_type sink  (::boost::asio::io_context& ios) const &;
0203
0204
0205
0206 };
0207
0208 #else
0209 using ::boost::process::detail::api::async_pipe;
0210 #endif
0211
0212
0213 }}
0214
0215
0216
0217 #endif