Boost C++ Libraries

PrevUpHomeNext

Class pistream

boost::process::pistream — Child process' output stream.

Synopsis

class pistream {
public:
// construct/copy/destruct
pistream(unspecified);

// public member functions
void close(void) ;
};

Description

The pistream class represents an output communication channel with the child process. The child process writes data to this stream and the parent process can read it through the pistream object. In other words, from the child's point of view, the communication channel is an output one, but from the parent's point of view it is an input one; hence the confusing pistream name.

pistream objects cannot be copied because they own the file handle they use to communicate with the child and because they buffer data that flows through the communication channel.

A pistream object behaves as a std::istream stream in all senses. The class is only provided because it must provide a method to let the caller explicitly close the communication channel.

Blocking remarks: Functions that read data from this stream can block if the associated file handle blocks during the read. As this class is used to communicate with child processes through anonymous pipes, the most typical blocking condition happens when the child has no more data to send to the pipe's system buffer. When this happens, the buffer eventually empties and the system blocks until the writer generates some data.

pistream construct/copy/destruct

  1. pistream(unspecified fh);

    Given a file handle, this constructor creates a new pistream object that owns the given file handle fh. Ownership of fh is transferred to the created pistream object.

    Requires:

    fh is valid.

    Postconditions:

    fh is invalid.

    The new pistream object owns fh.

pistream public member functions

  1. void close(void ) ;

    Explicitly closes the file handle managed by this stream. This function can be used by the user to tell the child process it's not willing to receive more data.

Copyright 2006 Julio M. Merino Vidal

PrevUpHomeNext