1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
|
# SPAWN - spawning system process
[![GitHub Actions status][actions-img]][actions]
[actions]: https://github.com/janestreet/spawn/actions
[actions-img]: https://github.com/janestreet/spawn/actions/workflows/workflow.yml/badge.svg
Spawn is a small library exposing only one function:
`Spawn.spawn`. Its purpose is to start command in the
background. Spawn aims to provide a few missing features of
`Unix.create_process` such as providing a working directory as well as
improving error reporting and performance.
Errors such as directory or program not found are properly reported as
`Unix.Unix_error` exceptions, on both Unix and Windows.
On Unix, Spawn uses `vfork` by default as it is often a lot faster
than fork. There is a benchmark comparing `Spawn.spawn` to
`Unix.create_process` in `spawn-lib/bench`. If you don't trust
`vfork`, you can set the environment variable `SPAWN_USE_FORK` to make
Spawn use `fork` instead.
## Portability
Spawn is expected to be fully portable. However, so far it has only
been tested on Linux, OSX and Windows.
## Implementation
On Windows, `Spawn.spawn` simply uses the
[CreateProcess][CreateProcess] Windows function.
Under Linux, it uses a custom implementation that relies on
`fork`/`vfork` followed by `execve`. Compared to other implementations
such as `Unix.create_process` or the [posix_spawn][posixspawn] C
library call, our implementations supports the following:
- setting the current working directory of the child process
- reporting errors from `execve` to the caller
To report `execve` errors, our implementation proceeds as follow: just
before calling `fork` or `vfork` we create a pipe with the `O_CLOEXEC`
flag. After forking, the parent reads from this pipe. If the `execve`
succeeds, the pipe get closed, the `read` in the parent returns 0
bytes and the parent concludes that the `execve` succceeded. If the
`execve` fails, the child process sends the error code to the parent
via the pipe and exits.
[CreateProcess]: https://docs.microsoft.com/en-gb/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessa?redirectedfrom=MSDN
[posixspawn]: http://man7.org/linux/man-pages/man3/posix_spawn.3.html
|
