| Home | Libraries | People | FAQ | More

## Class async_pipe

boost::process::async_pipe

## Synopsis

    // In header: <boost/process/async_pipe.hpp>

    class async_pipe {
    public:
      // types
      typedef platform_specific          native_handle_type;
      typedef platform_specific          handle_type;
      typedef handle_type::executor_type executor_type;

      // construct/copy/destruct
      async_pipe(boost::asio::io_context &);
      async_pipe(boost::asio::io_context &, boost::asio::io_context &);
      async_pipe(boost::asio::io_context &, const std::string &);
      async_pipe(boost::asio::io_context &, boost::asio::io_context &,
                 const std::string &);
      async_pipe(const async_pipe &);
      async_pipe(async_pipe &&);
      template<typename CharT, typename Traits = std::char_traits<CharT> >
        explicit async_pipe(boost::asio::io_context &,
                            const basic_pipe< CharT, Traits > &);
      template<typename CharT, typename Traits = std::char_traits<CharT> >
        explicit async_pipe(boost::asio::io_context &, boost::asio::io_context &,
                            const basic_pipe< CharT, Traits > &);
      template<typename CharT, typename Traits = std::char_traits<CharT> >
        async_pipe & operator=(const basic_pipe< CharT, Traits > &);
      async_pipe & operator=(const async_pipe &);
      async_pipe & operator=(async_pipe &&);
      ~async_pipe();

      // public member functions
      template<typename CharT, typename Traits = std::char_traits<CharT> >
        explicit operator basic_pipe< CharT, Traits >() const;
      void cancel();
      void close();
      void close(std::error_code &);
      bool is_open() const;
      void async_close();
      template<typename MutableBufferSequence>
        std::size_t read_some(const MutableBufferSequence &);
      template<typename MutableBufferSequence>
        std::size_t write_some(const MutableBufferSequence &);
      native_handle native_source() const;
      native_handle native_sink() const;
      template<typename MutableBufferSequence, typename ReadHandler>
        unspecified async_read_some(const MutableBufferSequence &, ReadHandler &&);
      template<typename ConstBufferSequence, typename WriteHandler>
        unspecified async_write_some(const ConstBufferSequence &, WriteHandler &&);
      const handle_type & sink() const;
      const handle_type & source() const;
      handle_type && sink();
      handle_type && source();
      handle_type source(::boost::asio::io_context &);
      handle_type sink(::boost::asio::io_context &);
      handle_type source(::boost::asio::io_context &) const;
      handle_type sink(::boost::asio::io_context &) const;
    };

## Description

Class implementing and asnychronous I/O-Object for use with boost.asio. It is based on the corresponding I/O Object, that is either boost::asio::windows::stream_handle or boost::asio::posix::stream_descriptor.

It can be used directly with boost::asio::async_read or async_write.

| Note
The object is copyable, but that does invoke a handle duplicate.

### `async_pipe` public types

1. typedef platform_specific native_handle_type;

   Typedef for the native handle representation.

   | Note
   This is the handle on the system, not the boost.asio class.

2. typedef platform_specific handle_type;

   Typedef for the handle representation of boost.asio.

### `async_pipe` public construct/copy/destruct

1.     async_pipe(boost::asio::io_context & ios);

   Construct a new `async_pipe`, does automatically open the pipe. Initializes source and sink with the same io_context.

   | Note
   Windows creates a named pipe here, where the name is automatically generated.

2.     async_pipe(boost::asio::io_context & ios_source,
                  boost::asio::io_context & ios_sink);

   Construct a new `async_pipe`, does automatically open the pipe.

   | Note
   Windows creates a named pipe here, where the name is automatically generated.

3.     async_pipe(boost::asio::io_context & ios, const std::string & name);

   Construct a new `async_pipe`, does automatically open. Initializes source and sink with the same io_context.

   | Note
   Windows restricts possible names.

4.     async_pipe(boost::asio::io_context & ios_source,
                  boost::asio::io_context & ios_sink, const std::string & name);

   Construct a new `async_pipe`, does automatically open.

   | Note
   Windows restricts possible names.

5.     async_pipe(const async_pipe & lhs);

   Copy-Constructor of the async pipe.

   | Note
   Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.

6.     async_pipe(async_pipe && lhs);

   Move-Constructor of the async pipe.

7.     template<typename CharT, typename Traits = std::char_traits<CharT> >
         explicit async_pipe(boost::asio::io_context & ios,
                             const basic_pipe< CharT, Traits > & p);

   Construct the async-pipe from a pipe.

   | Note
   Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.

8.     template<typename CharT, typename Traits = std::char_traits<CharT> >
         explicit async_pipe(boost::asio::io_context & ios_source,
                             boost::asio::io_context & ios_sink,
                             const basic_pipe< CharT, Traits > & p);

   Construct the async-pipe from a pipe, with two different io_context objects.

   | Note
   Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.

9.     template<typename CharT, typename Traits = std::char_traits<CharT> >
         async_pipe & operator=(const basic_pipe< CharT, Traits > & p);

   Assign a `basic_pipe`.

   | Note
   Windows requires a named pipe for this, if a the wrong type is used an exception is thrown.

10.     async_pipe & operator=(const async_pipe & lhs);

    Copy Assign a pipe.

    | Note
    Duplicates the handles.

11.     async_pipe & operator=(async_pipe && lhs);

    Move assign a pipe

12.     ~async_pipe();

    Destructor. Closes the pipe handles.

### `async_pipe` public member functions

1.     template<typename CharT, typename Traits = std::char_traits<CharT> >
         explicit operator basic_pipe< CharT, Traits >() const;

   Explicit cast to `basic_pipe`.

2.     void cancel();

   Cancel the current asynchronous operations.

3.     void close();

   Close the pipe handles.

4.     void close(std::error_code & ec);

   Close the pipe handles. While passing an error_code

5.     bool is_open() const;

   Check if the pipes are open.

6.     void async_close();

   Async close, i.e. close after current operation is completed.

   | Note
   There is no guarantee that this will indeed read the entire pipe-buffer

7.     template<typename MutableBufferSequence>
         std::size_t read_some(const MutableBufferSequence & buffers);

   Read some data from the handle.

   See the boost.asio documentation for more details.

8.     template<typename MutableBufferSequence>
         std::size_t write_some(const MutableBufferSequence & buffers);

   Write some data to the handle.

   See the boost.asio documentation for more details.

9.     native_handle native_source() const;

   Get the native handle of the source.

10.     native_handle native_sink() const;

    Get the native handle of the sink.

11.     template<typename MutableBufferSequence, typename ReadHandler>
          unspecified async_read_some(const MutableBufferSequence & buffers,
                                      ReadHandler && handler);

    Start an asynchronous read.

    See the boost.asio documentation for more details.

12.     template<typename ConstBufferSequence, typename WriteHandler>
          unspecified async_write_some(const ConstBufferSequence & buffers,
                                       WriteHandler && handler);

    Start an asynchronous write.

    See the boost.asio documentation for more details.

13.     const handle_type & sink() const;

    Get the asio handle of the pipe sink.

14.     const handle_type & source() const;

    Get the asio handle of the pipe source.

15.     handle_type && sink();

    Get the asio handle of the pipe sink. Qualified as rvalue.

16.     handle_type && source();

    Get the asio handle of the pipe source. Qualified as rvalue.

17.     handle_type source(::boost::asio::io_context & ios);

    Move the source out of this class and change the io_context. Qualified as rvalue.

    | Note
    Will always move.

18.     handle_type sink(::boost::asio::io_context & ios);

    Move the sink out of this class and change the io_context. Qualified as rvalue.

    | Note
    Will always move

19.     handle_type source(::boost::asio::io_context & ios) const;

    Copy the source out of this class and change the io_context.

    | Note
    Will always copy.

20.     handle_type sink(::boost::asio::io_context & ios) const;

    Copy the sink out of this class and change the io_context.

    | Note
    Will always copy