runtime: Replace "process is stopped" with "process exits"

proc(5) describes the following state entries in proc/[pid]/stat [1]
(for modern kernels):

* R Running
* S Sleeping in an interruptible wait
* D Waiting in uninterruptible disk sleep
* Z Zombie
* T Stopped (on a signal)
* t Tracing stop
* X Dead

and ps(1) has a bit more context [2] (for modern kernels):

* D uninterruptible sleep (usually IO)
* R running or runnable (on run queue)
* S interruptible sleep (waiting for an event to complete)
* T stopped by job control signal
* t stopped by debugger during the tracing
* X dead (should never be seen)
* Z defunct ("zombie") process, terminated but not reaped by its
  parent

So I expect "stopped" to mean "process still exists but is paused,
e.g. by SIGSTOP".  And I expect "exited" to mean "process has finished
and is either a zombie or dead".

After this commit, 'git grep -i stop' only turns up the "stopped"
state (which I've left alone for backwards compat), some poststop-hook
stuff, a reference in principles.md, a "stoppage" in LICENSE, and some
ChangeLog entries.

Also replace "container's process" with "container process" to match
usage in the rest of the repository.  After this commit:

  $ git grep -i "container process" | wc -l
  20
  $ git grep -i "container's process" | wc -l
  1

Also reword status entries to avoid "running", which is less precise
in our spec (e.g. it also includes "sleeping", "waiting", ...).

Also removes a "them" leftover from a partial plural -> singular
reroll of be594153 (Split create and start, 2016-04-01, #384).

[1]: http://man7.org/linux/man-pages/man5/proc.5.html
[2]: http://man7.org/linux/man-pages/man1/ps.1.html

Signed-off-by: W. Trevor King <wking@tremily.us>
This commit is contained in:
W. Trevor King 2016-05-26 22:47:52 -07:00
parent 7dce97bd7d
commit 9eb32c0e81
1 changed files with 6 additions and 5 deletions

View File

@ -15,9 +15,10 @@ This MUST be unique across all containers on this host.
There is no requirement that it be unique across hosts. There is no requirement that it be unique across hosts.
* **`status`**: (string) is the runtime state of the container. * **`status`**: (string) is the runtime state of the container.
The value MAY be one of: The value MAY be one of:
* `created`: the container has been created but the user-specified program has not yet been executed
* `running`: the container has been created and the user-specified program is running * `created`: the container process has neither exited nor executed the user-specified program
* `stopped`: the container has been created and the user-specified program has been executed but is no longer running * `running`: the container process has executed the user-specified program but has not exited
* `stopped`: the container process has exited
Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above. Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above.
* **`pid`**: (int) is the ID of the container process, as seen by the host. * **`pid`**: (int) is the ID of the container process, as seen by the host.
@ -55,8 +56,8 @@ The lifecycle describes the timeline of events that happen from when a container
However, some actions might only be available based on the current state of the container (e.g. only available while it is started). However, some actions might only be available based on the current state of the container (e.g. only available while it is started).
4. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container. 4. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container.
The runtime MUST run the user-specified program, as specified by [`process`](config.md#process). The runtime MUST run the user-specified program, as specified by [`process`](config.md#process).
5. The container's process is stopped. 5. The container process exits.
This MAY happen due to them erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked. This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked.
6. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container. 6. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container.
The container MUST be destroyed by undoing the steps performed during create phase (step 2). The container MUST be destroyed by undoing the steps performed during create phase (step 2).