IO redirection documentation issues
- Dominant language
- C++
- Stars
- 145
- Forks
- 151
- PR merge metrics
- No merged PRs in 30d
Description
I just got started with Boost.process, and noticed some things in the documentation that I hope can be addressed.
About [sync io](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_process/tutorial.html#boost_process.tutorial.io) it says:
> The pipe will cause a deadlock if you try to read after nm exited
Doesn't this suggest the example above it has a race condition? Also, doesn't the pipe just give EOF when reading from it after the process exited?
About [async IO](https://www.boost.org/doc/libs/1_67_0/doc/html/boost_process/tutorial.html#boost_process.tutorial.async_io)
> Passing an instance of boost::asio::io_service to the launching function automatically cause it to wait asynchronously for the exit, so no call of wait is needed.
What is waiting for the exit automaticaly? This suggests the `child` constructor does, but I suspect it is the `ios.run()` function that actually does the waiting?
> To make it even easier, you can use std::future for asynchronous operations (you will still need to pass a reference to a boost::asio::io_service) to the launching function, unless you use bp::system or bp::async_system
It seems the parenthesis are messed up here?
Also, perhaps it would be good to mention the fact that passing the `ios` is needed for `bp:child`, but not for `bp:system` (I suppose because it an create its own `ios` and run it, since `bp:system` is blocking).
```
boost::asio::io_service ios;
std::vector buf;
bp::child c(bp::search_path("g++"), "main.cpp", bp::std_out > boost::asio::buffer(buf), ios);
ios.run();
int result = c.exit_code();
```
This example suggests that the output is read into `buf`. Since `buf` does not get a particular size, this suggests that it is automatically resized (it is a vector after all). However, digging into `asio`, shows that these buffers are really simple, and just contain a reference to an existing buffer and size, without any support for resizing. In fact, running the above example leaves `buf` empty, so all output is actually discarded.
Defining `buf` with an initial size allows capturing output up to that size, but I couldn't find a way to actually get the amount of data put into the buffer (since the vector size is unaffected by writing to the buffer).
I'm not quite sure how this is intended to work, but with the current documentation, I got quite the wrong expectation from how this buffer stuff works. The next example on that page shows how to get an auto-resizing buffer by passing a `std::future` (which also works for `vector` it seems), but I wonder why a future is actually needed for that: Can it not just write to an existing string instead?
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.