Skip to content

Commit

Permalink
*: Replace "user-specified code" with "user-specified program"
Browse files Browse the repository at this point in the history
In [1], I'd proposed replacing our old "user-specified process" with
"user-specified code" to help distinguish between 'create' (cloning
the container process) and 'start' (signaling the container process to
execve or similar the user-specified $STUFF_FROM_THE_process_CONFIG).
That PR was rejected, although the renaming proposed there had already
landed via dd0cd21 (Add a 'status' field to our state struct,
2016-05-26, #462).

This PR attempts to find a common ground between "process" (preferred
by maintainers in #466 [2,3,4], but which I consider incorrect [5])
and "code" (which maintainers found confusing [3,4,6]).  The Linux
execve(2) has says "program" and unpacks that to "a binary executable,
or a script starting with a [shebang]" [7].  proc(5) documents
/proc/[pid]/exe by talking about "the executed command" [8].  The
POSIX exec docs call this the "process image" and talk about loading
it from the "new process image file" [9].

POSIX formally defines "command" [11], "executable file" [12], and
"program" [13].  The only reference to "process image" in the
definitions is in the "executable file" entry.  The "command"
definition is focused on the shell, the "executable file" definition
is focused on files, and the "program" definition talks about a
"prepared sequence of instructions to the system", so "program" seems
like the best fit.

[1]: #466
     Subject: runtime: Replace "user-specified process" with "user-specified code" in 'create'
[2]: #466 (comment)
[3]: #466 (comment)
[4]: #466 (comment)
[5]: #466 (comment)
[6]: #466 (comment)
[7]: http://man7.org/linux/man-pages/man2/execve.2.html
[8]: http://man7.org/linux/man-pages/man5/proc.5.html
[9]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html
[10]: https://git.kernel.org/cgit/docs/man-pages/man-pages.git/
[11]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_104
[12]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_154
[13]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_306

Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Nov 18, 2016
1 parent 7839cbb commit b1aff30
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 8 deletions.
2 changes: 1 addition & 1 deletion config.md
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,7 @@ Presently there are `Prestart`, `Poststart` and `Poststop`.
* [`Poststart`](#poststart) is a list of hooks to be run immediately after the container process is started
* [`Poststop`](#poststop) is a list of hooks to be run after the container process exits

Hooks allow one to run code before/after various lifecycle events of the container.
Hooks allow one to run programs before/after various lifecycle events of the container.
Hooks MUST be called in the listed order.
The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.

Expand Down
14 changes: 7 additions & 7 deletions runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ This MUST be unique across all containers on this host.
There is no requirement that it be unique across hosts.
* **`status`**: (string) is the runtime state of the container.
The value MAY be one of:
* `created`: the container has been created but the user-specified code has not yet been executed
* `running`: the container has been created and the user-specified code is running
* `stopped`: the container has been created and the user-specified code has been executed but is no longer running
* `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
* `stopped`: the container has been created and the user-specified program has been executed but is no longer running

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.
Expand Down Expand Up @@ -49,12 +49,12 @@ The lifecycle describes the timeline of events that happen from when a container
1. OCI compliant runtime's [`create`](runtime.md#create) command is invoked with a reference to the location of the bundle and a unique identifier.
2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md).
If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST generate an error.
While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified code (from [`process`](config.md#process)) MUST NOT be run at this time.
While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified program (from [`process`](config.md#process)) MUST NOT be run at this time.
Any updates to [`config.json`](config.md) after this step MUST NOT affect the container.
3. Once the container is created additional actions MAY be performed based on the features the runtime chooses to support.
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.
The runtime MUST run the user-specified code, 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.
This MAY happen due to them 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.
Expand Down Expand Up @@ -86,7 +86,7 @@ This operation MUST return the state of a container as specified in the [State](
This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container.
If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST generate an error and a new container MUST NOT be created.
Using the data in [`config.json`](config.md), this operation MUST create a new container.
This means that all of the resources associated with the container MUST be created, however, the user-specified code MUST NOT be run at this time.
This means that all of the resources associated with the container MUST be created, however, the user-specified program MUST NOT be run at this time.
If the runtime cannot create the container as specified in [`config.md`](config.md), it MUST generate an error and a new container MUST NOT be created.

Upon successful completion of this operation the `status` property of this container MUST be `created`.
Expand All @@ -102,7 +102,7 @@ Any changes made to the [`config.json`](config.md) file after this operation wil
This operation MUST generate an error if it is not provided the container ID.
Attempting to start a container that does not exist MUST generate an error.
Attempting to start an already started container MUST have no effect on the container and MUST generate an error.
This operation MUST run the user-specified code as specified by [`process`](config.md#process).
This operation MUST run the user-specified program as specified by [`process`](config.md#process).

Upon successful completion of this operation the `status` property of this container MUST be `running`.

Expand Down

0 comments on commit b1aff30

Please sign in to comment.