summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthew Heon <matthew.heon@gmail.com>2018-07-30 09:58:37 -0400
committerAtomic Bot <atomic-devel@projectatomic.io>2018-07-31 14:19:50 +0000
commitf4120f9662ec94f4972854e78b742dd96297d1eb (patch)
tree3f4c6730455f5932e523a3a05e4ba175652b92d0
parent1db70cce344724e091635bc8c6fa6c207450df68 (diff)
downloadpodman-f4120f9662ec94f4972854e78b742dd96297d1eb.tar.gz
podman-f4120f9662ec94f4972854e78b742dd96297d1eb.tar.bz2
podman-f4120f9662ec94f4972854e78b742dd96297d1eb.zip
Add additional comments on accessing state in API
The new state changes are potentially confusing to people writing API functions on containers or pods. Add comments to the structs on how to safely use them. Signed-off-by: Matthew Heon <matthew.heon@gmail.com> Closes: #1186 Approved by: rhatdan
-rw-r--r--libpod/container.go11
-rw-r--r--libpod/pod.go11
2 files changed, 20 insertions, 2 deletions
diff --git a/libpod/container.go b/libpod/container.go
index 77c94c7df..8ebb5570b 100644
--- a/libpod/container.go
+++ b/libpod/container.go
@@ -92,7 +92,16 @@ func (ns LinuxNS) String() string {
}
}
-// Container is a single OCI container
+// Container is a single OCI container.
+// All operations on a Container that access state must begin with a call to
+// syncContainer().
+// There is no guarantee that state exists in a readable state before
+// syncContainer() is run, and even if it does, its contents will be out of date
+// and must be refreshed from the database.
+// Generally, this requirement applies only to top-level functions; helpers can
+// assume that their callers handled this requirement. Generally speaking, if a
+// function takes the container lock and accesses any part of state, it should
+// syncContainer() immediately after locking.
// ffjson: skip
type Container struct {
config *ContainerConfig
diff --git a/libpod/pod.go b/libpod/pod.go
index 58becfa7a..9ea1f058b 100644
--- a/libpod/pod.go
+++ b/libpod/pod.go
@@ -12,7 +12,16 @@ import (
"github.com/sirupsen/logrus"
)
-// Pod represents a group of containers that may share namespaces
+// Pod represents a group of containers that are managed together.
+// Any operations on a Pod that access state must begin with a call to
+// updatePod().
+// There is no guarantee that state exists in a readable state before this call,
+// and even if it does its contents will be out of date and must be refreshed
+// from the database.
+// Generally, this requirement applies only to top-level functions; helpers can
+// assume their callers handled this requirement. Generally speaking, if a
+// function takes the pod lock and accesses any part of state, it should
+// updatePod() immediately after locking.
// ffjson: skip
type Pod struct {
config *PodConfig