basis/io/launcher/launcher-docs.factor

   1 ! Copyright (C) 2007, 2008 Slava Pestov.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax quotations kernel io io.files
   4 math calendar ;
   5 IN: io.launcher
   6
   7 ARTICLE: "io.launcher.command" "Specifying a command"
   8 "The " { $snippet "command" } " slot of a " { $link process } " can contain either a string or a sequence of strings. In the first case, the string is processed in an operating system-specific manner. In the second case, the first element is a program name and the remaining elements are passed to the program as command-line arguments." ;
   9
  10 ARTICLE: "io.launcher.detached" "Running processes in the background"
  11 "By default, " { $link run-process } " waits for the process to complete. To run a process without waiting for it to finish, set the " { $snippet "detached" } " slot of a " { $link process } ", or use the following word:"
  12 { $subsections run-detached } ;
  13
  14 ARTICLE: "io.launcher.environment" "Setting environment variables"
  15 "The " { $snippet "environment" } " slot of a " { $link process } " contains an association mapping environment variable names to values. The interpretation of environment variables is operating system-specific."
  16 $nl
  17 "The " { $snippet "environment-mode" } " slot controls how the environment of the current Factor instance is composed with the value of the " { $snippet "environment" } " slot:"
  18 { $subsections
  19     +prepend-environment+
  20     +replace-environment+
  21     +append-environment+
  22 }
  23 "The default value is " { $link +append-environment+ } "." ;
  24
  25 ARTICLE: "io.launcher.redirection" "Input/output redirection"
  26 "On all operating systems, the default input/output/error streams can be redirected."
  27 $nl
  28 "To specify redirection, set the " { $snippet "stdin" } ", " { $snippet "stdout" } " and " { $snippet "stderr" } " slots of a " { $link process } " to one of the following values:"
  29 { $list
  30     { { $link f } " - default value; the stream is either inherited from the current process, or is a " { $link <process-stream> } " pipe" }
  31     { { $link +closed+ } " - the stream is closed; reads will return end of file and writes will fails" }
  32     { { $link +stdout+ } " - a special value for the " { $snippet "stderr" } " slot only, indicating that the standard output and standard error streams should be merged" }
  33     { "a path name - the stream is sent to the given file, which must exist for input and is created automatically on output" }
  34     { "an " { $link appender } " wrapping a path name - output is sent to the end given file, as with " { $link <file-appender> } }
  35     { "a file stream or a socket - the stream is connected to the given Factor stream, which cannot be used again from within Factor and must be closed after the process has been started" }
  36 } ;
  37
  38 ARTICLE: "io.launcher.group" "Setting process groups"
  39 "The process group of a child process can be controlled by setting the " { $snippet "group" } " slot of a " { $link process } " tuple:"
  40 { $list
  41     { $link +same-group+ }
  42     { $link +new-group+ }
  43     { $link +new-session+ }
  44 }
  45 "The default value is " { $link +same-group+ } ", which denotes that the child process should be part of the process group of the parent process. The " { $link +new-group+ } " option creates a new process group, while the " { $link +new-session+ } " creates a new session." ;
  46
  47 ARTICLE: "io.launcher.priority" "Setting process priority"
  48 "The priority of the child process can be set by storing one of the below symbols in the " { $snippet "priority" } " slot of a " { $link process } " tuple:"
  49 { $list
  50     { $link +lowest-priority+ }
  51     { $link +low-priority+ }
  52     { $link +normal-priority+ }
  53     { $link +high-priority+ }
  54     { $link +highest-priority+ }
  55 }
  56 "The default value is " { $link f } ", which denotes that the child process should inherit the current process priority." ;
  57
  58 HELP: +closed+
  59 { $description "Possible value for the " { $snippet "stdin" } ", " { $snippet "stdout" } ", and " { $snippet "stderr" } " slots of a " { $link process } "." } ;
  60
  61 HELP: +stdout+
  62 { $description "Possible value for the " { $snippet "stderr" } " slot of a " { $link process } "." } ;
  63
  64 HELP: appender
  65 { $class-description "An object representing a file to append to. Instances are created with " { $link <appender> } "." } ;
  66
  67 HELP: <appender>
  68 { $values { "path" "a pathname string" } { "appender" appender } }
  69 { $description "Creates an object which may be stored in the " { $snippet "stdout" } " or " { $snippet "stderr" } " slot of a " { $link process } " instance." } ;
  70
  71 HELP: +prepend-environment+
  72 { $description "Possible value of " { $snippet "environment-mode" } " slot of a " { $link process } "."
  73 $nl
  74 "If this value is set, the child process environment consists of the value of the " { $snippet "environment" } " slot together with the current environment, with entries from the current environment taking precedence."
  75 $nl
  76 "This is used in situations where you want to spawn a child process with some default environment variables set, but allowing the user to override these defaults by changing the environment before launching Factor." } ;
  77
  78 HELP: +replace-environment+
  79 { $description "Possible value of " { $snippet "environment-mode" } " slot of a " { $link process } "."
  80 $nl
  81 "The child process environment consists of the value of the " { $snippet "environment" } " slot."
  82 $nl
  83 "This is used in situations where you want full control over a child process environment, perhaps for security or testing." } ;
  84
  85 HELP: +append-environment+
  86 { $description "Possible value of " { $snippet "environment-mode" } " slot of a " { $link process } "."
  87 $nl
  88 "The child process environment consists of the current environment together with the value of the " { $snippet "environment" } " key, with entries from the " { $snippet "environment" } " key taking precedence."
  89 $nl
  90 "This is used in situations where you want a spawn child process with some overridden environment variables." } ;
  91
  92 ARTICLE: "io.launcher.timeouts" "Process run-time timeouts"
  93 "The " { $snippet "timeout" } " slot of a " { $link process } " can be set to a " { $link duration } " specifying a maximum running time for the process. If " { $link wait-for-process } " is called and the process does not exit before the duration expires, it will be killed." ;
  94
  95 HELP: get-environment
  96 { $values { "process" process } { "env" "an association" } }
  97 { $description "Combines the current environment with the value of the " { $snippet "environment" } " slot of the " { $link process } " using the " { $snippet "environment-mode" } " slot." } ;
  98
  99 HELP: current-process-handle
 100 { $values { "handle" "a process handle" } }
 101 { $description "Returns the handle of the current process." }
 102 { $examples
 103   { $example
 104     "USING: io.launcher ;"
 105     "current-process-handle ."
 106     "6881"
 107   }
 108 } ;
 109
 110 HELP: run-process*
 111 { $values { "process" process } { "handle" "a process handle" } }
 112 { $contract "Launches a process." }
 113 { $notes "User code should call " { $link run-process } " instead." } ;
 114
 115 HELP: run-process
 116 { $values { "desc" "a launch descriptor" } { "process" process } }
 117 { $description "Launches a process. The object can either be a string, a sequence of strings or a " { $link process } ". See " { $link "io.launcher.descriptors" } " for details." }
 118 { $examples
 119   { $example
 120     "USING: io.launcher ;"
 121     "\"pwd\" run-process ."
 122     "/tmp"
 123     "T{ process"
 124     "    { command \"pwd\" }"
 125     "    { environment H{ } }"
 126     "    { environment-mode +append-environment+ }"
 127     "    { group +same-group+ }"
 128     "    { status 0 }"
 129     "}"
 130   }
 131 }
 132 { $notes "The output value can be passed to " { $link wait-for-process } " to get an exit code." } ;
 133
 134 HELP: run-detached
 135 { $values { "desc" "a launch descriptor" } { "process" process } }
 136 { $contract "Launches a process without waiting for it to complete. The object can either be a string, a sequence of strings or a " { $link process } ". See " { $link "io.launcher.descriptors" } " for details." }
 137 { $notes
 138     "This word is functionally identical to passing a " { $link process } " to " { $link run-process } " having the " { $snippet "detached" } " slot set."
 139     $nl
 140     "The output value can be passed to " { $link wait-for-process } " to get an exit code."
 141 } ;
 142
 143 HELP: process-failed
 144 { $values { "code" "an exit status" } }
 145 { $description "Throws a " { $link process-failed } " error." }
 146 { $error-description "Thrown by " { $link try-process } " if the process exited with a non-zero status code." } ;
 147
 148 HELP: try-process
 149 { $values { "desc" "a launch descriptor" } }
 150 { $description "Launches a process and waits for it to complete. If it exits with a non-zero status code, throws a " { $link process-failed } " error." }
 151 { $examples
 152   { $example
 153     "USING: continuations io.launcher ;"
 154     "[ \"ls --invalid-flag\" try-process ] [ ] recover ."
 155     "ls: unknown flag \"--invalid-flag\""
 156     "Try with ”ls --help” for more information."
 157     "T{ process-failed"
 158     "    { process"
 159     "         T{ process"
 160     "         { command \"ls --invalid-flag\" }"
 161     "         { environment H{ } }"
 162     "         { environment-mode +append-environment+ }"
 163     "         { group +same-group+ }"
 164     "         { status 2 }"
 165     "    }"
 166     "}"
 167   }
 168 } ;
 169
 170 { run-process try-process run-detached } related-words
 171
 172 HELP: kill-process
 173 { $values { "process" process } }
 174 { $description "Kills a running process. Does nothing if the process has already exited." }
 175 { $examples
 176   { $example
 177     "USING: io.launcher ;"
 178     "\"cat\" run-detached kill-process"
 179   }
 180 } ;
 181
 182 HELP: kill-process*
 183 { $values { "process" "process" } }
 184 { $contract "Kills a running process." }
 185 { $notes "User code should call " { $link kill-process } " instead." } ;
 186
 187 HELP: process
 188 { $class-description "A class representing a process. Instances are created by calling " { $link <process> } "." } ;
 189
 190 HELP: <process>
 191 { $values { "process" process } }
 192 { $description "Creates a new, empty process. It must be filled in before being passed to " { $link run-process } "." } ;
 193
 194 HELP: <process-stream>
 195 { $values
 196   { "desc" "a launch descriptor" }
 197   { "encoding" "an encoding descriptor" }
 198   { "stream" "a bidirectional stream" } }
 199 { $description "Launches a process and redirects its input and output via a pair of pipes which may be read and written as a stream with the given encoding." } ;
 200
 201 HELP: <process-reader>
 202 { $values
 203   { "desc" "a launch descriptor" }
 204   { "encoding" "an encoding descriptor" }
 205   { "stream" "an input stream" } }
 206 { $description "Launches a process and redirects its output via a pipe which may be read as a stream with the given encoding." } ;
 207
 208 HELP: <process-writer>
 209 { $values
 210   { "desc" "a launch descriptor" }
 211   { "encoding" "an encoding descriptor" }
 212   { "stream" "an output stream" }
 213 }
 214 { $description "Launches a process and redirects its input via a pipe which may be written to as a stream with the given encoding." } ;
 215
 216 HELP: with-process-stream
 217 { $values
 218   { "desc" "a launch descriptor" }
 219   { "encoding" "an encoding descriptor" }
 220   { "quot" quotation }
 221 }
 222 { $description "Launches a process and redirects its input and output via a pair of pipes. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to these pipes." } ;
 223
 224 HELP: with-process-reader
 225 { $values
 226   { "desc" "a launch descriptor" }
 227   { "encoding" "an encoding descriptor" }
 228   { "quot" quotation }
 229 }
 230 { $description "Launches a process and redirects its output via a pipe. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to this pipe." }
 231 { $examples
 232   { $example
 233     "USING: io.launcher ;"
 234     "\"ls -dl /etc\" utf8 [ contents ] with-process-reader ."
 235     "\"drwxr-xr-x 213 root root 12288 mar 11 18:52 /etc\\n\""
 236   }
 237 } ;
 238
 239 HELP: with-process-writer
 240 { $values
 241   { "desc" "a launch descriptor" }
 242   { "encoding" "an encoding descriptor" }
 243   { "quot" quotation }
 244 }
 245 { $description "Launches a process and redirects its input via a pipe. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to this pipe." } ;
 246
 247 HELP: wait-for-process
 248 { $values { "process" process } { "status" object } }
 249 { $description "If the process is still running, waits for it to exit, otherwise outputs the status code immediately. Can be called multiple times on the same process." }
 250 { $notes "The status code is operating system specific; it may be an integer, or another object (the latter is the case on Unix if the process was killed by a signal). However, one cross-platform behavior code can rely on is that a status code of 0 indicates success." } ;
 251
 252 ARTICLE: "io.launcher.descriptors" "Launch descriptors"
 253 "Words which launch processes can take either a command line string, a sequence of command line arguments, or a " { $link process } "."
 254 $nl
 255 "Strings and string arrays are wrapped in a new empty " { $link process } " with the " { $snippet "command" } " slot set. This covers basic use-cases where no launch parameters need to be set."
 256 $nl
 257 "A " { $link process } " instance can be created directly and passed to launching words for more control. It must be a fresh instance which has never been spawned before. To spawn a process several times from the same descriptor, " { $link clone } " the descriptor first." ;
 258
 259 ARTICLE: "io.launcher.lifecycle" "The process lifecycle"
 260 "A freshly instantiated " { $link process } " represents a set of launch parameters."
 261 { $subsections
 262     process
 263     <process>
 264 }
 265 "Words for launching processes take a fresh process which has never been started before as input, and output a copy as output."
 266 { $subsections process-started? }
 267 "The " { $link process } " instance output by launching words contains all original slot values in addition to the " { $snippet "handle" } " slot, which indicates the process is currently running."
 268 { $subsections process-running? }
 269 "It is possible to wait for a process to exit:"
 270 { $subsections wait-for-process }
 271 "A running process can also be killed:"
 272 { $subsections kill-process } ;
 273
 274 ARTICLE: "io.launcher.launch" "Launching processes"
 275 "Launching processes:"
 276 { $subsections
 277     run-process
 278     try-process
 279     run-detached
 280 }
 281 "Redirecting standard input and output to a pipe:"
 282 { $subsections
 283     <process-reader>
 284     <process-writer>
 285     <process-stream>
 286 }
 287 "Combinators built on top of the above:"
 288 { $subsections
 289     with-process-reader
 290     with-process-writer
 291     with-process-stream
 292 } ;
 293
 294 ARTICLE: "io.launcher.examples" "Launcher examples"
 295 "Starting a command and waiting for it to finish:"
 296 { $code
 297     "\"ls /etc\" run-process"
 298 }
 299 "Starting a program in the background:"
 300 { $code
 301     "{ \"emacs\" \"foo.txt\" } run-detached"
 302 }
 303 "Running a command, throwing an exception if it exits unsuccessfully:"
 304 { $code
 305     "\"make clean all\" try-process"
 306 }
 307 "Running a command, throwing an exception if it exits unsuccessfully or if it takes too long to run:"
 308 { $code
 309     "<process>"
 310     "    \"make test\" >>command"
 311     "    5 minutes >>timeout"
 312     "try-process"
 313 }
 314 "Running a command, throwing an exception if it exits unsuccessfully, and redirecting output and error messages to a log file:"
 315 { $code
 316     "<process>"
 317     "    \"make clean all\" >>command"
 318     "    \"log.txt\" >>stdout"
 319     "    +stdout+ >>stderr"
 320     "try-process"
 321 }
 322 "Running a command, appending error messages to a log file, and reading the output for further processing:"
 323 { $code
 324     "\"log.txt\" ascii <file-appender> ["
 325     "    <process>"
 326     "        swap >>stderr"
 327     "        \"report\" >>command"
 328     "    ascii <process-reader> stream-lines sort reverse [ print ] each"
 329     "] with-disposal"
 330 } ;
 331
 332 ARTICLE: "io.launcher" "Operating system processes"
 333 "The " { $vocab-link "io.launcher" } " vocabulary implements cross-platform process launching."
 334 { $subsections
 335     "io.launcher.examples"
 336     "io.launcher.descriptors"
 337     "io.launcher.launch"
 338 }
 339 "Advanced topics:"
 340 { $subsections
 341     "io.launcher.lifecycle"
 342     "io.launcher.command"
 343     "io.launcher.detached"
 344     "io.launcher.environment"
 345     "io.launcher.redirection"
 346     "io.launcher.priority"
 347     "io.launcher.group"
 348     "io.launcher.timeouts"
 349 } ;
 350
 351 ABOUT: "io.launcher"