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

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