3.17. kink/PROCESS

Control the current process and subprocesses.

3.17.1. PROCESS.pid

`pid` returns the current process id in an int num.

Example:

:PROCESS.require_from('kink/')

stdout.print_line(PROCESS.pid.repr) # => 123

3.17.2. PROCESS.env(Env_name)

`env` returns the str of the environment variable specified by `Env_name`.

Preconditions:

• `Env_name` must be a str

• The process must have the specified environment variable

Case sensitivity of `Env_name` depends on the host system. Typically, it is case sensitive on Unix systems, and case insensitive on Windows systems.

Example:

:PROCESS.require_from('kink/')

stdout.print_line(PROCESS.env('PATH').repr)
# => "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

3.17.3. PROCESS.have_env?(Env_name)

`have_env?` returns whether the process has the environment variable specified by `Env_name`.

Precondition:

• `Env_name` must be a str

Example:

:PROCESS.require_from('kink/')

stdout.print_line(PROCESS.have_env?('PATH').repr) # => true
stdout.print_line(PROCESS.have_env?('NO_SUCH_ENV').repr)  # => false

Case sensitivity of `Env_name` depends on the host system. Typically, it is case sensitive on Unix systems, and case insensitive on Windows systems.

3.17.4. PROCESS.exit(Exit_status)

`exit` terminates the process running the runtime system with the `Exit_status`.

Precondition:

• `Exit_status` must be an int num in the range [-2147483648, 2147483647].

3.17.5. PROCESS.start(Command_and_args ...[$config={}])

`start` launches a subprocess by the command specified by `Command_and_args`.

Preconditions:

• `Command_and_args` must be a vec of strs

• `Command_and_args` must contain at least one element

• $config, if given, must be a fun which takes a val of `start_conf` type

Result:

• If `start` succeeds to launch a subprocess, it tail-calls the success cont with the val of `process` type which represents the launched subprocess. By default, it returns the `process` val.

• If `start` fails to launch a subprocess, it tail-calls the error cont with an error message. By default, it raises an exception.

Example:

:PROCESS.require_from('kink/')

:Ls <- PROCESS.start(['ls' '-1' '/']) # command: ls -1 /
stdout.print_line(Ls.wait) # => 0

The source of the standard input and the destination of the standard output and standard error of the subprocess can be configured.

:PROCESS.require_from('kink/')
:CONTROL.require_from('kink/')
:WRAP_SCANNER.require_from('kink/io/')
:CHARSET.require_from('kink/charset/')

:Lines <- CONTROL.with_on_exit{(:on_exit)
  :Ls = PROCESS.start(['ls' '-1' '/']){(:C)
    C.stdout_to_pipe
  }
  on_exit{ Ls.wait }
  :Stdout = Ls.stdout
  on_exit{ Stdout.close }
  :Scanner = WRAP_SCANNER.new(Stdout CHARSET.utf8)
  :loop <- {(:Lines)
    Scanner.scan_line.for_maybe(
      {(:L) loop(Lines + [L]) }
      { Lines }
    )
  }
  loop([])
}
stdout.print_line(Lines.repr) # => ["bin\n" "boot\n" "dev\n" "etc\n" "home\n" ,,,]

See `start_conf` for details.

3.17.6. type start_conf

Conf val type of PROCESS.start.

Invocation of stdin_xxx methods overwrites configuration of precedent invocation of stdin_xxx methods. In the next example, the subprocess reads stdin from /etc/passwd.

:PROCESS.require_from('kink/')

:Process <- PROCESS.start(['grep' 'nologin']){(:C)
  C.stdin_from_pipe # pipe is not used
  C.stdin_from_file('/etc/passwd')
}
Process.wait
# Output:
#   daemon:x:1:1:daemon:/usr/sbin:/usr/sbin/nologin
#   bin:x:2:2:bin:/bin:/usr/sbin/nologin
#   ...

The same is true for stdout_xxx and stderr_xxx methods.

C.stdin_inherit

`stdin_inherit` specifies that the subprocess inherits standard input from the current process.

This is the default option for the standard input.

C.stdin_from_pipe

`stdin_from_pipe` specifies that bytes of the standard input of the subprocess comes from the pipe output of the current process.

If you specify `stdin_from_pipe`, you can call P.stdin to get the pipe linked to the subprocess.

C.stdin_from_file(File_path)

`stdin_from_file` specifies that bytes of the standard input of the subprocess comes from the file on `File_path`.

Precondition:

• `File_path` must be a str.

If the file cannot be opened, PROCESS.start fails.

C.stdout_inherit

`stdout_inherit` specifies that the subprocess inherits the standard output of the current process.

This is the default option for the standard output.

C.stdout_to_pipe

`stdout_to_pipe` specifies that the standard output of the subprocess goes to the pipe input of the current process.

If you specify `stdout_to_pipe`, you can call P.stdout to get the pipe input linked to the subprocess.

C.stdout_to_overwrite(File_path)

`stdout_to_overwrite` specifies that the standard output of the subprocess goes to a file specified by `File_path` by OVERWRITE mode.

Precondition:

• `File_path` must be a str

If the file cannot be opened, PROCESS.start fails.

See kink/io/FILE for OVERWRITE mode.

C.stdout_to_append(File_path)

`stdout_to_append` specifies that the standard output of the subprocess goes to a file specified by `File_path` by APPEND mode.

Precondition:

• `File_path` must be a str

If the file cannot be opened, PROCESS.start fails.

See kink/io/FILE for APPEND mode.

C.stderr_inherit

`stderr_inherit` specifies that the subprocess inherits the standard error of the current process.

This is the default option for the standard error.

C.stderr_to_pipe

`stderr_to_pipe` specifies that the standard error of the subprocess goes to the pipe input of the current process.

If you specify `stderr_to_pipe`, you can call P.stderr to get the pipe input liked to the subprocess.

C.stderr_to_overwrite(File_path)

`stderr_to_overwrite` specifies that the standard error of the subprocess goes to a file specified by `File_path` by OVERWRITE mode.

Precondition:

• `File_path` must be a str

If the file cannot be opened, PROCESS.start fails.

See kink/io/FILE for OVERWRITE mode.

C.stderr_to_append(File_path)

`stderr_to_append` specifies that the standard error of the subprocess goes to a file specified by `File_path` by APPEND mode.

Precondition:

• `File_path` must be a str

If the file cannot be opened, PROCESS.start fails.

See kink/io/FILE for APPEND mode.

C.stderr_to_stdout

`stderr_to_stdout` specifies that the standard error of the subprocess goes to its standard output.

It is similar to specifying `2>&1` in Unix sh.

C.dir(Dir_path)

`dir` specifies `Dir_path` as the working directory of the subprocess.

Precondition:

• Dir_path must be a str

If the subprocess cannot change directory to `Dir_path`, PROCESS.start fails.

C.set_env(Env_name Env_val)

`set_env` specifies that the subprocess has the environment variable with the name `Env_name` and the value `Env_val`.

Preconditions:

• `Env_name` must be a str

• `Env_val` must be a str

Case sensitivity of `Env_name` depends on the host system. Typically, it is case sensitive on Unix systems, and case insensitive on Windows systems.

C.unset_env(Env_name)

`unset_env` specifies that the subprocess does not have the environment variable with the name `Env_name`.

Precondition:

• `Env_name` must be a str

Case sensitivity of `Env_name` depends on the host system. Typically, it is case sensitive on Unix systems, and case insensitive on Windows systems.

C.on_success($success_cont)

`on_success` specifies that $success_cont is used as the success cont of PROCESS.start.

Precondition:

• $success_cont must be a fun which takes a `process` val.

If `on_success` is not called, CORE.id is used as the success cont.

C.on_error($error_cont)

`on_error` specifies that $error_cont is used as the error cont of PROCESS.start.

Precondition:

• $error_cont must be a fun which takes an error message str.

If `on_error` is not called, a fun which raises an exception is used as the default error cont.

3.17.7. type process

`process` is a type of subprocesses launched by PROCESS.start.

P.wait(...[$config={}])

`wait` waits until the subprocess becomes terminated status.

Precondition:

• $config is a fun which takes `wait_conf` val.

Result:

• If the subprocess becomes terminated status before timeout, `wait` tail-calls the terminate cont with the exit status as an int num. The default terminate cont returns the exit status.

• If the subprocess does not become terminated status before timeout, `wait` tail-calls the timeout cont with no args. The default timeout cont raises an exception.

If C.timeout is not called, no timeout is set.

P.stdin

`stdin` returns the pipe `output` linked to the standard input of the subprocess.

Precondition:

• C.stdin_from_pipe must be called for the `start_conf` val.

P.stdout

`stdout` returns the pipe `input` linked to the standard output of the subprocess.

Precondition:

• C.stdout_to_pipe must be called for the `start_conf` val.

P.stderr

`stderr` returns the pipe `input` linked to the standard error of the subprocess.

Precondition:

• C.stderr_to_pipe must be called for the `start_conf` val.

3.17.8. type wait_conf

Conf val type of P.wait.

C.timeout(Seconds)

`timeout` specifies that P.wait times out in `Seconds` seconds.

• `Seconds` must be a non-negative num

C.on_terminate($terminate_cont)

`on_terminate` specifies $terminate_cont as the terminate cont of P.wait.

Precondition:

• $terminate_cont must be a fun which takes an int num as the exit status.

If `on_terminate` is not called, CORE.id is used as the terminate cont.

C.on_timeout($timeout_cont)

`on_timeout` specifies $timeout_cont as the timeout cont of P.wait.

Precondition:

• $timeout_cont must be a fun which takes no arg.

If `on_timeout` is not called, a fun which raises an exception is used as the default timeout cont.