From f4120f9662ec94f4972854e78b742dd96297d1eb Mon Sep 17 00:00:00 2001 From: Matthew Heon Date: Mon, 30 Jul 2018 09:58:37 -0400 Subject: 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 Closes: #1186 Approved by: rhatdan --- libpod/container.go | 11 ++++++++++- libpod/pod.go | 11 ++++++++++- 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 -- cgit v1.2.3-54-g00ecf