1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Design Rationale</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../process.html" title="Chapter 29. Boost.Process"> 10<link rel="prev" href="tutorial.html" title="Tutorial"> 11<link rel="next" href="extend.html" title="Extensions"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="tutorial.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../process.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="extend.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="boost_process.design"></a><a class="link" href="design.html" title="Design Rationale">Design Rationale</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="design.html#boost_process.design.scope">Scope</a></span></dt> 32<dt><span class="section"><a href="design.html#boost_process.design.interface_style">Interface Style</a></span></dt> 33<dt><span class="section"><a href="design.html#boost_process.design.arg_cmd_style">Arguments/Command 34 Style</a></span></dt> 35<dt><span class="section"><a href="design.html#boost_process.design.plat_ext">Extensions</a></span></dt> 36</dl></div> 37<div class="section"> 38<div class="titlepage"><div><div><h3 class="title"> 39<a name="boost_process.design.scope"></a><a class="link" href="design.html#boost_process.design.scope" title="Scope">Scope</a> 40</h3></div></div></div> 41<p> 42 This library is meant to give a wrapper around the different OS-specific 43 methods to launch processes. Its aim is to provide all functionality that 44 is available on those systems and allow the user to do all related things, 45 which require using the OS APIs. 46 </p> 47<p> 48 <span class="bold"><strong>This library does not try to provide a full library 49 for everything process related.</strong></span> In many discussions the proposal 50 was made to build boost.process into a DSEL <a href="#ftn.boost_process.design.scope.f0" class="footnote" name="boost_process.design.scope.f0"><sup class="footnote">[29]</sup></a> of some sort. This is not the goal, it rather provides the facilities 51 to build such a DSEL-library on top of it. Therefore the library also does 52 <span class="bold"><strong>not</strong></span> force any particular use (such as only 53 asynchronous communication) on its user. It rather could be integrated with 54 such a library. 55 </p> 56</div> 57<div class="section"> 58<div class="titlepage"><div><div><h3 class="title"> 59<a name="boost_process.design.interface_style"></a><a class="link" href="design.html#boost_process.design.interface_style" title="Interface Style">Interface Style</a> 60</h3></div></div></div> 61<p> 62 Boost.Process does use a very particular style when constructing a process. 63 This is because a process holds many properties, which are not members of 64 the actual child class. Those properties are in many cases not accessible 65 by the father process, for example when using environments. Here the child 66 process can modify its own environment, but there is no way for the father 67 process to know. That means, that a child process has properties that cannot 68 be accessed in C++. 69 </p> 70<p> 71 This now leads to the two styles supported and mixed by this library. Overloading 72 and properties. Consider that you may want to launch a process passing a 73 number of arguments. This is supported in both styles, and would look like 74 this: 75 </p> 76<p> 77</p> 78<pre class="programlisting"><span class="identifier">system</span><span class="special">(</span><span class="string">"gcc"</span><span class="special">,</span> <span class="string">"--version"</span><span class="special">);</span> <span class="comment">//overloading</span> 79<span class="identifier">system</span><span class="special">(</span><span class="string">"gcc"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">={</span><span class="string">"--version"</span><span class="special">});</span> <span class="comment">//property style.</span> 80</pre> 81<p> 82 </p> 83<p> 84 Both styles can also be mixed in some cases. 85 </p> 86<p> 87</p> 88<pre class="programlisting"><span class="identifier">system</span><span class="special">(</span><span class="string">"gcc"</span><span class="special">,</span> <span class="string">"-c"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">+={</span><span class="string">"main.cpp"</span><span class="special">});</span> 89</pre> 90<p> 91 </p> 92<p> 93 In the following section the available styles will be described. Note that 94 the overload style is implemented via type traits, so the types will be listed. 95 </p> 96<div class="caution"><table border="0" summary="Caution"> 97<tr> 98<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td> 99<th align="left">Caution</th> 100</tr> 101<tr><td align="left" valign="top"><p> 102 There is no guarantee in which order the arguments will be applied! There 103 is however a guarantee for arguments belonging together, i.e. the string 104 argument and the args property will be evaluated in the order given. 105 </p></td></tr> 106</table></div> 107</div> 108<div class="section"> 109<div class="titlepage"><div><div><h3 class="title"> 110<a name="boost_process.design.arg_cmd_style"></a><a class="link" href="design.html#boost_process.design.arg_cmd_style" title="Arguments/Command Style">Arguments/Command 111 Style</a> 112</h3></div></div></div> 113<p> 114 When passing arguments to the process, two styles are provided, the cmd-style 115 and the exe-/args-style. 116 </p> 117<p> 118 The cmd style will interpret the string as a sequence of the exe and arguments 119 and parse them as such, while the exe-/args-style will interpret each string 120 as an argument. 121 </p> 122<div class="table"> 123<a name="boost_process.design.arg_cmd_style.id"></a><p class="title"><b>Table 29.1. Cmd vs Exe/Args</b></p> 124<div class="table-contents"><table class="table" summary="Cmd vs Exe/Args"> 125<colgroup> 126<col> 127<col> 128<col> 129</colgroup> 130<thead><tr> 131<th> 132 <p> 133 String 134 </p> 135 </th> 136<th> 137 <p> 138 Cmd 139 </p> 140 </th> 141<th> 142 <p> 143 Exe/Args 144 </p> 145 </th> 146</tr></thead> 147<tbody><tr> 148<td> 149 <p> 150 "gcc --version" 151 </p> 152 </td> 153<td> 154 <p> 155 {"gcc", "--version"} 156 </p> 157 </td> 158<td> 159 <p> 160 {"\"gcc --version\""} 161 </p> 162 </td> 163</tr></tbody> 164</table></div> 165</div> 166<br class="table-break"><p> 167 When using the overloading variant, a single string will result in a cmd 168 interpretation, several strings will yield a exe-args interpretation. Both 169 versions can be set explicitly: 170 </p> 171<p> 172</p> 173<pre class="programlisting"><span class="identifier">system</span><span class="special">(</span><span class="string">"grep -c false /etc/passwd"</span><span class="special">);</span> <span class="comment">//cmd style</span> 174<span class="identifier">system</span><span class="special">(</span><span class="string">"grep"</span><span class="special">,</span> <span class="string">"-c"</span><span class="special">,</span> <span class="string">"false"</span><span class="special">,</span> <span class="string">"/etc/passwd"</span><span class="special">);</span> <span class="comment">//exe-/args-</span> 175 176<span class="identifier">system</span><span class="special">(</span><span class="identifier">cmd</span><span class="special">=</span><span class="string">"grep -c false /etc/passwd"</span><span class="special">);</span> <span class="comment">//cmd style</span> 177<span class="identifier">system</span><span class="special">(</span><span class="identifier">exe</span><span class="special">=</span><span class="string">"grep"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">={</span><span class="string">"-c"</span><span class="special">,</span> <span class="string">"false"</span><span class="special">,</span> <span class="string">"/etc/passwd"</span><span class="special">});</span> <span class="comment">//exe-/args-</span> 178</pre> 179<p> 180 </p> 181<div class="note"><table border="0" summary="Note"> 182<tr> 183<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 184<th align="left">Note</th> 185</tr> 186<tr><td align="left" valign="top"><p> 187 If a '"' sign is used in the argument style, it will be passed as 188 part of the argument. If the same effect is wanted with the cmd syntax, 189 it ought to be escaped, i.e. '\"'. 190 </p></td></tr> 191</table></div> 192<div class="note"><table border="0" summary="Note"> 193<tr> 194<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 195<th align="left">Note</th> 196</tr> 197<tr><td align="left" valign="top"><p> 198 The <code class="computeroutput"><span class="identifier">PATH</span></code> variable will 199 automatically be searched in the command style, but the one of the launching 200 process, not the one passed to the child process. 201 </p></td></tr> 202</table></div> 203</div> 204<div class="section"> 205<div class="titlepage"><div><div><h3 class="title"> 206<a name="boost_process.design.plat_ext"></a><a class="link" href="design.html#boost_process.design.plat_ext" title="Extensions">Extensions</a> 207</h3></div></div></div> 208<p> 209 The simplest form to extend functionality is to provide another handler, 210 which will be called on the respective events on process launching. The names 211 are: 212 </p> 213<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 214<li class="listitem"> 215 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">process</span><span class="special">::</span><span class="identifier">on_setup</span></code> 216 </li> 217<li class="listitem"> 218 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">process</span><span class="special">::</span><span class="identifier">on_error</span></code> 219 </li> 220<li class="listitem"> 221 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">process</span><span class="special">::</span><span class="identifier">on_success</span></code> 222 </li> 223</ul></div> 224<p> 225 As an example: 226 </p> 227<p> 228</p> 229<pre class="programlisting"><span class="identifier">child</span> <span class="identifier">c</span><span class="special">(</span><span class="string">"ls"</span><span class="special">,</span> <span class="identifier">on_setup</span><span class="special">([](){</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"On Setup"</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;});</span> 230</pre> 231<p> 232 </p> 233<div class="note"><table border="0" summary="Note"> 234<tr> 235<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 236<th align="left">Note</th> 237</tr> 238<tr><td align="left" valign="top"><p> 239 On posix all those callbacks will be handled by this process, not the created 240 one. This is different for the posix extensions, which can be executed 241 on the forked process. 242 </p></td></tr> 243</table></div> 244</div> 245<div class="footnotes"> 246<br><hr style="width:100; text-align:left;margin-left: 0"> 247<div id="ftn.boost_process.design.scope.f0" class="footnote"><p><a href="#boost_process.design.scope.f0" class="para"><sup class="para">[29] </sup></a> 248 Domain Specific Embedded Language 249 </p></div> 250</div> 251</div> 252<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 253<td align="left"></td> 254<td align="right"><div class="copyright-footer">Copyright © 2006-2012 Julio M. Merino Vidal, Ilya Sokolov, 255 Felipe Tanus, Jeff Flinn, Boris Schaeling<br>Copyright © 2016 Klemens D. Morgenstern<p> 256 Distributed under the Boost Software License, Version 1.0. (See accompanying 257 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 258 </p> 259</div></td> 260</tr></table> 261<hr> 262<div class="spirit-nav"> 263<a accesskey="p" href="tutorial.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../process.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="extend.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 264</div> 265</body> 266</html> 267
