1. docker
  2. Commit b654b6244d6d63a0758029488a95feb446e089bd
Browse code

Improve description of Running and Paused booleans

Commit abd72d4008dde7ee8249170d49eb4bc963c51e24 added
a "FIXME" comment to the container "State", mentioning
that a container cannot be both "Running" and "Paused".

This comment was incorrect, because containers on
Linux actually _must_ be running in order to be
paused.

This patch adds additional information both in a
comment, and in the API documentation to clarify
that these booleans are not mutually exclusive.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Sebastiaan van Stijn authored on 2017/05/19 19:29:54
Showing 3 changed files
api/swagger.yaml
History View file @ b654b62
... ... 
@@ -3107,10 +3107,22 @@ paths:
3107 3107 
                 type: "object"
3108 3108 
                 properties:
3109 3109 
                   Status:
3110 
-                    description: "The status of the container. For example, `running` or `exited`."
3110 
+                    description: |
3111 
+                      The status of the container. For example, `"running"` or `"exited"`.
3111 3112 
                     type: "string"
3113 
+                    enum: ["created", "running", "paused", "restarting", "removing", "exited", "dead"]
3112 3114 
                   Running:
3113 
-                    description: "Whether this container is running."
3115 
+                    description: |
3116 
+                      Whether this container is running.
3117 
+
3118 
+                      Note that a running container can be _paused_. The `Running` and `Paused`
3119 
+                      booleans are not mutually exclusive:
3120 
+
3121 
+                      When pausing a container (on Linux), the cgroups freezer is used to suspend
3122 
+                      all processes in the container. Freezing the process requires the process to
3123 
+                      be running. As a result, paused containers are both `Running` _and_ `Paused`.
3124 
+
3125 
+                      Use the `Status` field instead to determin if a container's state is "running".
3114 3126 
                     type: "boolean"
3115 3127 
                   Paused:
3116 3128 
                     description: "Whether this container is paused."
api/types/types.go
History View file @ b654b62
... ... 
@@ -277,7 +277,7 @@ type Health struct {
277 277 
 // ContainerState stores container's running state
278 278 
 // it's part of ContainerJSONBase and will return by "inspect" command
279 279 
 type ContainerState struct {
280 
-	Status     string
280 
+	Status     string // String representation of the container state. Can be one of "created", "running", "paused", "restarting", "removing", "exited", or "dead"
281 281 
 	Running    bool
282 282 
 	Paused     bool
283 283 
 	Restarting bool
container/state.go
History View file @ b654b62
... ... 
@@ -17,8 +17,10 @@ import (
17 17 
 // functions defined against State to run against Container.
18 18 
 type State struct {
19 19 
 	sync.Mutex
20 
-	// FIXME: Why do we have both paused and running if a
21 
-	// container cannot be paused and running at the same time?
20 
+	// Note that `Running` and `Paused` are not mutually exclusive:
21 
+	// When pausing a container (on Linux), the cgroups freezer is used to suspend
22 
+	// all processes in the container. Freezing the process requires the process to
23 
+	// be running. As a result, paused containers are both `Running` _and_ `Paused`.
22 24 
 	Running           bool
23 25 
 	Paused            bool
24 26 
 	Restarting        bool