summaryrefslogtreecommitdiff
path: root/libpod
diff options
context:
space:
mode:
authorMatthew Heon <matthew.heon@gmail.com>2018-07-19 12:05:14 -0400
committerMatthew Heon <matthew.heon@gmail.com>2018-07-24 16:12:31 -0400
commit8f91678a499d29cb5221153e223f5e896cb1b5b1 (patch)
tree03387bcb482c41a76f9240ef254e141789b815eb /libpod
parent84afa32493335e74d6094c3723c53cf38ac9e6bb (diff)
downloadpodman-8f91678a499d29cb5221153e223f5e896cb1b5b1.tar.gz
podman-8f91678a499d29cb5221153e223f5e896cb1b5b1.tar.bz2
podman-8f91678a499d29cb5221153e223f5e896cb1b5b1.zip
Update documentation for the State interface
Include details on how namespaces interact with the state. Signed-off-by: Matthew Heon <matthew.heon@gmail.com>
Diffstat (limited to 'libpod')
-rw-r--r--libpod/state.go105
1 files changed, 72 insertions, 33 deletions
diff --git a/libpod/state.go b/libpod/state.go
index 6239e399a..1b82349b3 100644
--- a/libpod/state.go
+++ b/libpod/state.go
@@ -10,70 +10,109 @@ type State interface {
Refresh() error
// SetNamespace() sets the namespace for the store, and will determine
- // what containers are retrieved with container and pod retrieval calls
+ // what containers are retrieved with container and pod retrieval calls.
+ // A namespace of "", the empty string, acts as no namespace, and
+ // containers and pods in all namespaces will be returned.
SetNamespace(ns string) error
- // Return a container from the database from its full ID
+ // Return a container from the database from its full ID.
+ // If the container is not in the set namespace, an error will be
+ // returned.
Container(id string) (*Container, error)
// Return a container from the database by full or partial ID or full
- // name
+ // name.
+ // Containers not in the set namespace will be ignored.
LookupContainer(idOrName string) (*Container, error)
- // Check if a container with the given full ID exists in the database
+ // Check if a container with the given full ID exists in the database.
+ // If the container exists but is not in the set namespace, false will
+ // be returned.
HasContainer(id string) (bool, error)
- // Adds container to state
- // The container cannot be part of a pod
+ // Adds container to state.
+ // The container cannot be part of a pod.
// The container must have globally unique name and ID - pod names and
- // IDs also conflict with container names and IDs
+ // IDs also conflict with container names and IDs.
+ // The container must be in the set namespace if a namespace has been
+ // set.
+ // All containers this container depends on must be part of the same
+ // namespace and must not be joined to a pod.
AddContainer(ctr *Container) error
- // Removes container from state
- // Containers that are part of pods must use RemoveContainerFromPod
+ // Removes container from state.
+ // Containers that are part of pods must use RemoveContainerFromPod.
+ // The container must be part of the set namespace.
RemoveContainer(ctr *Container) error
- // UpdateContainer updates a container's state from the backing store
+ // UpdateContainer updates a container's state from the backing store.
+ // The container must be part of the set namespace.
UpdateContainer(ctr *Container) error
- // SaveContainer saves a container's current state to the backing store
+ // SaveContainer saves a container's current state to the backing store.
+ // The container must be part of the set namespace.
SaveContainer(ctr *Container) error
// ContainerInUse checks if other containers depend upon a given
- // container
+ // container.
// It returns a slice of the IDs of containers which depend on the given
// container. If the slice is empty, no container depend on the given
// container.
- // A container cannot be removed if other containers depend on it
+ // A container cannot be removed if other containers depend on it.
+ // The container being checked must be part of the set namespace.
ContainerInUse(ctr *Container) ([]string, error)
- // Retrieves all containers presently in state
+ // Retrieves all containers presently in state.
+ // If a namespace is set, only containers within the namespace will be
+ // returned.
AllContainers() ([]*Container, error)
- // Accepts full ID of pod
+ // Accepts full ID of pod.
+ // If the pod given is not in the set namespace, an error will be
+ // returned.
Pod(id string) (*Pod, error)
- // Accepts full or partial IDs (as long as they are unique) and names
+ // Accepts full or partial IDs (as long as they are unique) and names.
+ // Pods not in the set namespace are ignored.
LookupPod(idOrName string) (*Pod, error)
- // Checks if a pod with the given ID is present in the state
+ // Checks if a pod with the given ID is present in the state.
+ // If the given pod is not in the set namespace, false is returned.
HasPod(id string) (bool, error)
- // Check if a pod has a container with the given ID
+ // Check if a pod has a container with the given ID.
+ // The pod must be part of the set namespace.
PodHasContainer(pod *Pod, ctrID string) (bool, error)
- // Get the IDs of all containers in a pod
+ // Get the IDs of all containers in a pod.
+ // The pod must be part of the set namespace.
PodContainersByID(pod *Pod) ([]string, error)
- // Get all the containers in a pod
+ // Get all the containers in a pod.
+ // The pod must be part of the set namespace.
PodContainers(pod *Pod) ([]*Container, error)
- // Adds pod to state
+ // Adds pod to state.
+ // The pod must be part of the set namespace.
+ // The pod's name and ID must be globally unique.
AddPod(pod *Pod) error
- // Removes pod from state
- // Only empty pods can be removed from the state
+ // Removes pod from state.
+ // Only empty pods can be removed from the state.
+ // The pod must be part of the set namespace.
RemovePod(pod *Pod) error
- // Remove all containers from a pod
+ // Remove all containers from a pod.
// Used to simultaneously remove containers that might otherwise have
- // dependency issues
- // Will fail if a dependency outside the pod is encountered
+ // dependency issues.
+ // Will fail if a dependency outside the pod is encountered.
+ // The pod must be part of the set namespace.
RemovePodContainers(pod *Pod) error
- // AddContainerToPod adds a container to an existing pod
- // The container given will be added to the state and the pod
+ // AddContainerToPod adds a container to an existing pod.
+ // The container given will be added to the state and the pod.
+ // The container and its dependencies must be part of the given pod,
+ // and the given pod's namespace.
+ // The pod must be part of the set namespace.
+ // The pod must already exist in the state.
+ // The container's name and ID must be globally unique.
AddContainerToPod(pod *Pod, ctr *Container) error
- // RemoveContainerFromPod removes a container from an existing pod
- // The container will also be removed from the state
+ // RemoveContainerFromPod removes a container from an existing pod.
+ // The container will also be removed from the state.
+ // The container must be in the given pod, and the pod must be in the
+ // set namespace.
RemoveContainerFromPod(pod *Pod, ctr *Container) error
- // UpdatePod updates a pod's state from the database
+ // UpdatePod updates a pod's state from the database.
+ // The pod must be in the set namespace.
UpdatePod(pod *Pod) error
- // SavePod saves a pod's state to the database
+ // SavePod saves a pod's state to the database.
+ // The pod must be in the set namespace.
SavePod(pod *Pod) error
- // Retrieves all pods presently in state
+ // Retrieves all pods presently in state.
+ // If a namespace has been set, only pods in that namespace will be
+ // returned.
AllPods() ([]*Pod, error)
}