Update comments in BoltDB and In-Memory states

Better explain the inner workings of both state types in comments
to make reviews and changes easier.

Signed-off-by: Matthew Heon <matthew.heon@gmail.com>

3 files changed, 55 insertions, 16 deletions

diff --git a/docs/podman.1.md b/docs/podman.1.md
index 41c427ec6..1ca420d12 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -37,11 +37,11 @@ Path to where the cpu performance results should be written
 
 **--log-level**
 
-log messages above specified level: debug, info, warn, error (default), fatal or panic
+Log messages above specified level: debug, info, warn, error (default), fatal or panic
 
 **--namespace**
 
-set libpod namespace. Namespaces are used to separate groups of containers and pods in libpod's state.
+Set libpod namespace. Namespaces are used to separate groups of containers and pods in libpod's state.
 When namespace is set, created containers and pods will join the given namespace, and only containers and pods in the given namespace will be visible to Podman.
 
 **--root**=**value**
diff --git a/libpod/boltdb_state.go b/libpod/boltdb_state.go
index 24785248f..afbaecffb 100644
--- a/libpod/boltdb_state.go
+++ b/libpod/boltdb_state.go
@@ -21,6 +21,34 @@ type BoltState struct {
 	runtime        *Runtime
 }
 
+// A brief description of the format of the BoltDB state:
+// At the top level, the following buckets are created:
+// - idRegistryBkt: Maps ID to Name for containers and pods.
+//   Used to ensure container and pod IDs are globally unique.
+// - nameRegistryBkt: Maps Name to ID for containers and pods.
+//   Used to ensure container and pod names are globally unique.
+// - nsRegistryBkt: Maps ID to namespace for all containers and pods.
+//   Used during lookup operations to determine if a given ID is in the same
+//   namespace as the state.
+// - ctrBkt: Contains a sub-bucket for each container in the state.
+//   Each sub-bucket has config and state keys holding the container's JSON
+//   encoded configuration and state (respectively), an optional netNS key
+//   containing the path to the container's network namespace, a dependencies
+//   bucket containing the container's dependencies, and an optional pod key
+//   containing the ID of the pod the container is joined to.
+// - allCtrsBkt: Map of ID to name containing only containers. Used for
+//   container lookup operations.
+// - podBkt: Contains a sub-bucket for each pod in the state.
+//   Each sub-bucket has config and state keys holding the pod's JSON encoded
+//   configuration and state, plus a containers sub bucket holding the IDs of
+//   containers in the pod.
+// - allPodsBkt: Map of ID to name containing only pods. Used for pod lookup
+//   operations.
+// - runtimeConfigBkt: Contains configuration of the libpod instance that
+//   initially created the database. This must match for any further instances
+//   that access the database, to ensure that state mismatches with
+//   containers/storage do not occur.
+
 // NewBoltState creates a new bolt-backed state database
 func NewBoltState(path, lockDir string, runtime *Runtime) (State, error) {
 	state := new(BoltState)
@@ -296,7 +324,9 @@ func (s *BoltState) LookupContainer(idOrName string) (*Container, error) {
 		var id []byte
 		ctrExists := ctrBucket.Bucket([]byte(idOrName))
 		if ctrExists != nil {
-			// A full container ID was given
+			// A full container ID was given.
+			// It might not be in our namespace, but
+			// getContainerFromDB() will handle that case.
 			id = []byte(idOrName)
 		} else {
 			// They did not give us a full container ID.
@@ -759,7 +789,9 @@ func (s *BoltState) LookupPod(idOrName string) (*Pod, error) {
 		var id []byte
 		podExists := podBkt.Bucket([]byte(idOrName))
 		if podExists != nil {
-			// A full pod ID was given
+			// A full pod ID was given.
+			// It might not be in our namespace, but getPodFromDB()
+			// will handle that case.
 			id = []byte(idOrName)
 		} else {
 			// They did not give us a full pod ID.
diff --git a/libpod/in_memory_state.go b/libpod/in_memory_state.go
index d421a5e8b..8bdd0881c 100644
--- a/libpod/in_memory_state.go
+++ b/libpod/in_memory_state.go
@@ -14,16 +14,27 @@ import (
 
 // An InMemoryState is a purely in-memory state store
 type InMemoryState struct {
-	pods             map[string]*Pod
-	containers       map[string]*Container
-	ctrDepends       map[string][]string
-	podContainers    map[string]map[string]*Container
-	nameIndex        *registrar.Registrar
-	idIndex          *truncindex.TruncIndex
-	namespace        string
+	// Maps pod ID to pod struct.
+	pods map[string]*Pod
+	// Maps container ID to container struct.
+	containers map[string]*Container
+	// Maps container ID to a list of IDs of dependencies.
+	ctrDepends map[string][]string
+	// Maps pod ID to a map of container ID to container struct.
+	podContainers map[string]map[string]*Container
+	// Global name registry - ensures name uniqueness and performs lookups.
+	nameIndex *registrar.Registrar
+	// Global ID registry - ensures ID uniqueness and performs lookups.
+	idIndex *truncindex.TruncIndex
+	// Namespace the state is joined to.
+	namespace string
+	// Maps namespace name to local ID and name registries for looking up
+	// pods and containers in a specific namespace.
 	namespaceIndexes map[string]*namespaceIndex
 }
 
+// namespaceIndex contains name and ID registries for a specific namespace.
+// This is used for namespaces lookup operations.
 type namespaceIndex struct {
 	nameIndex *registrar.Registrar
 	idIndex   *truncindex.TruncIndex
@@ -339,11 +350,7 @@ func (s *InMemoryState) ContainerInUse(ctr *Container) ([]string, error) {
 func (s *InMemoryState) AllContainers() ([]*Container, error) {
 	ctrs := make([]*Container, 0, len(s.containers))
 	for _, ctr := range s.containers {
-		if s.namespace != "" {
-			if ctr.config.Namespace == s.namespace {
-				ctrs = append(ctrs, ctr)
-			}
-		} else {
+		if s.namespace == "" || ctr.config.Namespace == s.namespace {
 			ctrs = append(ctrs, ctr)
 		}
 	}