12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394 |
- [section:design Design Rationale]
- [section Scope]
- This library is meant to give an wrapper around the different OS-specific methods
- to launch processes. Its aim is to provide all functionality that is available on
- those systems and allow the user to do all related things, which require using the OS APIs.
- [*This library does not try to provide a full library for everything process related]
- In many discussions the proposal was made to build boost.process into a DSEL [footnote Domain Specific Embedded Language] of some sort.
- This is not the goal, it rather provides the facilities to build such a DSEL-Library on top of it.
- Therefore the library also does [*not] force any particular use (such as only asynchronous communication) on its user.
- It rather could be integrated with such a library.
- [endsect]
- [section Interface Style]
- Boost.Process does use a very particular style when constructing a process.
- This is because a process holds many properties, which are not members of the actual child class.
- Those properties are in many cases not accessible by the father process, for example when using environments.
- Here the child process can modify its own environment, but there is no way for the father process to know.
- That means, that a child process has properties that cannot be accessed in C++.
- This now leads to the two styles supported and mixed by this library. Overloading and properties.
- Consider that you may want to launch a process passing a number of arguments. This is supported in both styles, and would look like this:
- ```
- system("gcc", "--version"); //overloading
- system("gcc", args={"--version"}); //property style.
- ```
- Both styles can also be mixed in some cases.
- ```
- system("gcc", "-c", args+={"main.cpp"});
- ```
- In the following section the avaible styles will be described. Note that the
- overload style is implemented via type traits, so the types will be listed.
- [caution There is no guarantee in which order the arguments will be applied!
- There is however a guarantee for arguments belonging together, i.e. the string
- argument and the args property will be evaluated in the order given.]
- [endsect]
- [section:arg_cmd_style Arguments/Command Style]
- When passing arguments to the process, two styles are provided, the cmd-style and the exe-/args-style.
- The cmd style will interpret the string as a sequence of the exe and arguments and parse them as such, while the exe-/args-style will
- interpret each string as an argument.
- [table:id Cmd vs Exe/Args
- [[String] [Cmd] [Exe/Args]]
- [["gcc --version"] [{"gcc", "--version"}] [{"\\"gcc --version\\""}]]
- ]
- When using the overloading variant, a single string will result in a cmd interpretation,
- several strings will yield a exe-args interpretation. Both version can be set explicitly:
- ```
- system("grep -c false /etc/passwd"); //cmd style
- system("grep", "-c", "false", "/etc/passwd"); //exe-/args-
- system(cmd="grep -c false /etc/passwd"); //cmd style
- system(exe="grep", args={"-c", "false", "/etc/passwd"}); //exe-/args-
- ```
- [note If a '"' sign is used in the argument style, it will be passed as part of the argument.
- If the same effect it wanted with the cmd syntax, it ought to be escaped, i.e. '\\\"'. ]
- [note The `PATH` variable will automatically be searched in the command style,
- but the one of the launching process, not the one passed to the child process.]
- [endsect]
- [section:plat_ext Extensions]
- The simplest form to extend functionality is to provide another handler, which
- will be called on the respective events on process launching. The names are:
- *`boost::process::on_setup`
- *`boost::process::on_error`
- *`boost::process::on_success`
- As an example:
- ```
- child c("ls", on_setup([](){cout << "On Setup" << endl;});
- ```
- [note On posix all those callbacks will be handled by this process, not the created one.
- This is different for the posix extensions, which can be executed on the forked process.]
- [endsect]
- [endsect]
|