[boost] Initial review of Boost Process

Subject: [boost] Initial review of Boost Process
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-02-15 22:36:29

This is an initial review of Boost Process based just on reading the 
documentation, I hope to find some time to try out the library within 
the next few days.

I am pretty knowledgable about child processes, more on Windows than 
Linux, but I understand well how starting another process works in general.

I was able to generate the documentation from the jamfile in the doc 
directory of the library. The documentation updated the targets 
successfully but there were a few messages which need to be fixed:

"xslt-xsltproc.windows 
bin\msvc-10.0\debug\threading-multi\autodoc-xml.doxygen
xslt-xsltproc.windows 
bin\msvc-10.0\debug\threading-multi\autodoc-xml.boostbook
common.copy autodoc.xml
bin\msvc-10.0\debug\threading-multi\autodoc-xml.boostbook
         1 file(s) copied.
xslt-xsltproc.windows bin\msvc-10.0\debug\threading-multi\process.docbook
Cannot find method named 'boost::process::detail::basic_status::async_wait'
Cannot find method named 'boost::process::detail::basic_status::async_wait'
Cannot find class named 'boost::system::system_error'
Cannot find class named 'boost::system::system_error'
Cannot find class named 'boost::filesystem::filesystem_error'
Reference to class 'pipe' is ambiguous. Found:
               Match in namespace ::boost::process::
               Match in namespace ::boost::process::behavior::
Reference to class 'pipe' is ambiguous. Found:
               Match in namespace ::boost::process::
               Match in namespace ::boost::process::behavior::
xslt-xsltproc-dir.windows html\standalone_HTML.manifest
Computing chunks...
Writing standalone_HTML.manifest
...updated 13 targets..."

In the "Configuring runtime contexts" topic I did not feel there is a 
clear explanation of some of the context members. What is the 'env' 
member ? The synopsis says it is of type 'environment' but there is no 
explanation what this means. Is the parent's environment inherited by 
the child process ? Are there any environment variables automatically 
inherited by the child process ?

The context's streams member and its meaning is incomplete. What is the 
stream_type ? The various built-in functors, which are described as 
behaviors are also incomplete in their explanation. What these are, and 
what they do, needs to be explained.

The synopsis doc for the stream_id says it is a "NativeStreamId" but it 
does not tell one what that is. Are streams other than standard input, 
standard output, or standard error supported ?

In the "Communicating with Child Processes" documentation, it mentions 
the various pipe behaviors. An example is given of synchronous I/O using 
'pipe'. But then the last line tells us that for asynchronous I/O one 
uses 'pipe'. This is confusing.

In the "Asynchronous I/O" section it repeats again that one uses 'pipe' 
for ansynchronous I/O but then the example uses 'async_pipe' instead. 
Again this is very confusing.

In the "Terminating a Process" section it does not explain how a process 
is terminated. I think that needs to be in there.

In the "Creating new stream behaviors" section I am shown example code 
for redirecting a stream but there is no explanation of how this works. 
There needs to be.

It would be nice if some mention were made about Boost.Interprocess and 
if there is any redundancy between Process and the facilities in the 
Interprocess library. Also any needed explanation of how one uses 
Process with the facilities in Boost.Interprocess would be helpful.

I think the documentation is organized well but is too sparse in places. 
I will try to use Process and hopefully I can review it further. But I 
would not initially recommend it with documentation which is this 
incomplete. The design does seem both clean and focused on what 
creating, communicating, and controlling a child process is supposed to 
do, and I like it that the library seeks to do specific things and not 
try to overextend itself. But it clearly needs a fuller doc.

Edward Diener