Skip to content

Commit

Permalink
Drop exec, pause, resume, and signal
Browse files Browse the repository at this point in the history
All of these require state information to be shared between funC
invocations (to map from a container ID to the
cgroups/namespaces/etc.), and after today's meeting we may be backing
away from that [1,2].  Even if we keep a requirement for sharing state
between funC invocations, we don't want to specify these IPC-requiring
commands until we have more clarity on that requirement in the spec.

On systems like Solaris, the kernel maintains a registry of container
IDs directly, so they don't need an external registry [3].  But
without a consensus around the minimal amount of inter-process state
sharing, we don't want to require container ID → state lookups in the
command-line spec.  Once we have more clarity on a minimal required
mechanism (e.g. Julz's --state-file [4,5,6]), we can add them back in
with an API that all runtimes can easily support (although runtimes
are of course free to provide more convenient APIs as additional
extensions).

Pause, resume, and signal are still in the current lifecycle pull
request [7], but I've requested they be removed until we have more
clarity around the basic lifecycle [8].

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2015/opencontainers.2015-12-02-18.01.html
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2015/opencontainers.2015-12-02-18.01.log.html#l-79
[3]: #3 (comment)
[4]: #3 (comment)
[5]: #3 (comment)
[6]: #3 (comment)
[7]: mrunalp/specs@bd549a2#diff-b84a8d65d8ed53f4794cd2db7e8ea731R48
[8]: https://github.com/opencontainers/specs/pull/231/files#r45532412

Signed-off-by: W. Trevor King <wking@tremily.us>
Reviewed-by: Mike Brown <brownwm@us.ibm.com>
Reviewed-by: Jesse Butler <jeeves.butler@gmail.com>
Reviewed-by: Julian Friedman <julz.friedman@uk.ibm.com>
  • Loading branch information
wking committed Dec 8, 2015
1 parent 933b55d commit b922732
Showing 1 changed file with 0 additions and 78 deletions.
78 changes: 0 additions & 78 deletions runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,84 +67,6 @@ $ echo $?
42
```

### exec

Runs a secondary process in the given container.

* *Options*
* *`--process <PATH>`* Override `process.json` with an alternative path. The path may not support seeking (e.g. `/dev/fd/3`).
* *Arguments*
* *`<ID>`* The container ID to join.
* *Standard streams:* The runtime must attach its standard streams directly to the application process without inspection.
* *Exit code:* The runtime must exit with the application process's exit code.

If the main application (launched by `start`) dies, all other processes in its container will be killed [TODO: link to lifecycle docs explaining this].

Example:
```sh
# in a directory with a process.json that echos "goodbye" and exits 43
$ funC exec hello-1
goodbye
$ echo $?
43
```

### pause

Pause all processes in a container.

* *Options*
* *`--wait`* Block until the process is completely paused.
Otherwise return immediately after initiating the pause, which may happen before the pause is complete.
* *Arguments*
* *`<ID>`* The container ID to join.
* *Exit code:* 0 on success, non-zero on error.

Example:
```sh
$ funC pause --wait hello-1
$ echo $?
0
```

### resume

Unpause all processes in a container.

* *Options*
* *`--wait`* Block until the process is completely unpaused.
Otherwise return immediately after initiating the unpause, which may happen before the unpause is complete.
* *Arguments*
* *`<ID>`* The container ID to join.
* *Exit code:* 0 on success, non-zero on error.

Example:
```sh
$ funC resume hello-1
$ echo $?
0
```

### signal

Sends a signal to the container.

* *Options*
* *`--signal <SIGNAL>`* The signal to send.
This must be one of the valid POSIX signals, although runtimes on non-POSIX systems must translate the POSIX name to their platorm's analogous signal.
Defaults to TERM.
* *Arguments*
* *`<ID>`* The container ID to join.
* *Exit code:* 0 on success, non-zero on error.
A 0 exit status does not imply the process has exited (as it may have caught the signal).

Example:
```sh
$ funC signal --signal KILL hello-1
$ echo $?
0
```

[posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02
[posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
[posix-locale-encoding: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup
Expand Down

0 comments on commit b922732

Please sign in to comment.