From 38462f5f513f29977843d08efbe1c5c85655225b Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Fri, 29 Mar 2013 21:13:59 -0700 Subject: [PATCH] Add comments in graph.go Upstream-commit: 99b36c2c326ccc11e726eee6ee78a0baf166ef96 Component: engine --- components/engine/graph.go | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/components/engine/graph.go b/components/engine/graph.go index 6f93f2b827..09bc1d5bed 100644 --- a/components/engine/graph.go +++ b/components/engine/graph.go @@ -10,10 +10,13 @@ import ( "time" ) +// A Graph is a store for versioned filesystem images, and the relationship between them. type Graph struct { Root string } +// NewGraph instanciates a new graph at the given root path in the filesystem. +// `root` will be created if it doesn't exist. func NewGraph(root string) (*Graph, error) { abspath, err := filepath.Abs(root) if err != nil { @@ -34,6 +37,8 @@ func (graph *Graph) IsNotExist(err error) bool { return err != nil && strings.Contains(err.Error(), "does not exist") } +// Exists returns true if an image is registered at the given id. +// If the image doesn't exist or if an error is encountered, false is returned. func (graph *Graph) Exists(id string) bool { if _, err := graph.Get(id); err != nil { return false @@ -41,6 +46,7 @@ func (graph *Graph) Exists(id string) bool { return true } +// Get returns the image with the given id, or an error if the image doesn't exist. func (graph *Graph) Get(id string) (*Image, error) { // FIXME: return nil when the image doesn't exist, instead of an error img, err := LoadImage(graph.imageRoot(id)) @@ -54,6 +60,7 @@ func (graph *Graph) Get(id string) (*Image, error) { return img, nil } +// Create creates a new image and registers it in the graph. func (graph *Graph) Create(layerData Archive, container *Container, comment string) (*Image, error) { img := &Image{ Id: GenerateId(), @@ -71,6 +78,8 @@ func (graph *Graph) Create(layerData Archive, container *Container, comment stri return img, nil } +// Register imports a pre-existing image into the graph. +// FIXME: pass img as first argument func (graph *Graph) Register(layerData Archive, img *Image) error { if err := ValidateId(img.Id); err != nil { return err @@ -95,6 +104,7 @@ func (graph *Graph) Register(layerData Archive, img *Image) error { return nil } +// Mktemp creates a temporary sub-directory inside the graph's filesystem. func (graph *Graph) Mktemp(id string) (string, error) { tmp, err := NewGraph(path.Join(graph.Root, ":tmp:")) if err != nil { @@ -106,6 +116,9 @@ func (graph *Graph) Mktemp(id string) (string, error) { return tmp.imageRoot(id), nil } +// Garbage returns the "garbage", a staging area for deleted images. +// This allows images ot be deleted atomically by os.Rename(), instead of +// os.RemoveAll() which is prone to race conditions func (graph *Graph) Garbage() (*Graph, error) { return NewGraph(path.Join(graph.Root, ":garbage:")) } @@ -124,6 +137,7 @@ func isNotEmpty(err error) bool { return strings.Contains(err.Error(), " not empty") } +// Delete atomically removes an image from the graph. func (graph *Graph) Delete(id string) error { garbage, err := graph.Garbage() if err != nil { @@ -150,6 +164,7 @@ func (graph *Graph) Delete(id string) error { return nil } +// Undelete moves an image back from the garbage to the main graph func (graph *Graph) Undelete(id string) error { garbage, err := graph.Garbage() if err != nil { @@ -158,6 +173,7 @@ func (graph *Graph) Undelete(id string) error { return os.Rename(garbage.imageRoot(id), graph.imageRoot(id)) } +// GarbageCollect definitely deletes all images moved to the garbage func (graph *Graph) GarbageCollect() error { garbage, err := graph.Garbage() if err != nil { @@ -166,6 +182,7 @@ func (graph *Graph) GarbageCollect() error { return os.RemoveAll(garbage.Root) } +// Map returns a list of all images in the graph, addressable by ID func (graph *Graph) Map() (map[string]*Image, error) { // FIXME: this should replace All() all, err := graph.All() @@ -179,6 +196,7 @@ func (graph *Graph) Map() (map[string]*Image, error) { return images, nil } +// All returns a list of all images in the graph func (graph *Graph) All() ([]*Image, error) { var images []*Image err := graph.WalkAll(func(image *Image) { @@ -187,6 +205,8 @@ func (graph *Graph) All() ([]*Image, error) { return images, err } +// WalkAll iterates over each image in the graph, and passes it to a handler. +// The walking order is undetermined. func (graph *Graph) WalkAll(handler func(*Image)) error { files, err := ioutil.ReadDir(graph.Root) if err != nil { @@ -203,6 +223,10 @@ func (graph *Graph) WalkAll(handler func(*Image)) error { return nil } +// ByParent returns a lookup table of images by their parent. +// If an image of id ID has 3 children images, then the value for key ID +// will be a list of 3 images. +// If an image has no children, it will not have an entry in the table. func (graph *Graph) ByParent() (map[string][]*Image, error) { byParent := make(map[string][]*Image) err := graph.WalkAll(func(image *Image) { @@ -219,6 +243,8 @@ func (graph *Graph) ByParent() (map[string][]*Image, error) { return byParent, err } +// Heads returns all heads in the graph, keyed by id. +// A head is an image which is not the parent of another image in the graph. func (graph *Graph) Heads() (map[string]*Image, error) { heads := make(map[string]*Image) byParent, err := graph.ByParent()