From b654b6244d6d63a0758029488a95feb446e089bd Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Fri, 19 May 2017 12:29:54 +0200
Subject: [PATCH] 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>
---
 api/swagger.yaml   | 16 ++++++++++++++--
 api/types/types.go |  2 +-
 container/state.go |  6 ++++--
 3 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/api/swagger.yaml b/api/swagger.yaml
index 10cf361d47..4bce7d6610 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -3107,10 +3107,22 @@ paths:
                 type: "object"
                 properties:
                   Status:
-                    description: "The status of the container. For example, `running` or `exited`."
+                    description: |
+                      The status of the container. For example, `"running"` or `"exited"`.
                     type: "string"
+                    enum: ["created", "running", "paused", "restarting", "removing", "exited", "dead"]
                   Running:
-                    description: "Whether this container is running."
+                    description: |
+                      Whether this container is running.
+
+                      Note that a running container can be _paused_. The `Running` and `Paused`
+                      booleans are not mutually exclusive:
+
+                      When pausing a container (on Linux), the cgroups freezer is used to suspend
+                      all processes in the container. Freezing the process requires the process to
+                      be running. As a result, paused containers are both `Running` _and_ `Paused`.
+
+                      Use the `Status` field instead to determin if a container's state is "running".
                     type: "boolean"
                   Paused:
                     description: "Whether this container is paused."
diff --git a/api/types/types.go b/api/types/types.go
index fa9f1b0de1..c905466e29 100644
--- a/api/types/types.go
+++ b/api/types/types.go
@@ -277,7 +277,7 @@ type Health struct {
 // ContainerState stores container's running state
 // it's part of ContainerJSONBase and will return by "inspect" command
 type ContainerState struct {
-	Status     string
+	Status     string // String representation of the container state. Can be one of "created", "running", "paused", "restarting", "removing", "exited", or "dead"
 	Running    bool
 	Paused     bool
 	Restarting bool
diff --git a/container/state.go b/container/state.go
index 027377f4e3..e99fe008bb 100644
--- a/container/state.go
+++ b/container/state.go
@@ -17,8 +17,10 @@ import (
 // functions defined against State to run against Container.
 type State struct {
 	sync.Mutex
-	// FIXME: Why do we have both paused and running if a
-	// container cannot be paused and running at the same time?
+	// Note that `Running` and `Paused` are not mutually exclusive:
+	// When pausing a container (on Linux), the cgroups freezer is used to suspend
+	// all processes in the container. Freezing the process requires the process to
+	// be running. As a result, paused containers are both `Running` _and_ `Paused`.
 	Running           bool
 	Paused            bool
 	Restarting        bool