Skip to content

Commit

Permalink
Update some docstrings
Browse files Browse the repository at this point in the history 
Update some docstrings to reflect changes to APIs (names are usually
lists now instead of specific values, big data and flags are now present
in some structures), mark Crawl() and its return type as deprecated, and
clarify that IDs are assigned automatically if a caller doesn't supply
one to be used when creating an item.

Signed-off-by: Nalin Dahyabhai <nalin@redhat.com>
  • Loading branch information
@nalind
nalind committed Oct 5, 2016
1 parent 6a6198a commit d4ee4f6
Show file tree
Hide file tree
Showing 4 changed files with 100 additions and 59 deletions.
31 changes: 22 additions & 9 deletions storage/containers.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,15 @@ var (
ErrContainerUnknown = errors.New("container not known")
)

// A Container is a reference to a read-write layer with a metadata string.
// A Container is a reference to a read-write layer with metadata.
type Container struct {
// ID is either one specified at create-time or a randomly-generated value.
// ID is either one which was specified at create-time, or a random
// value which was generated by the library.
ID string `json:"id"`

// Names is an optional set of user-defined convenience values.
// Names is an optional set of user-defined convenience values. The
// container can be referred to by its ID or any of its names. Names
// are unique among containers.
Names []string `json:"names,omitempty"`

// ImageID is the ID of the image which was used to create the container.
Expand All @@ -32,9 +35,16 @@ type Container struct {
// read-write layer.
LayerID string `json:"layer"`

Metadata string `json:"metadata,omitempty"`
BigDataNames []string `json:"big-data-names,omitempty"`
Flags map[string]interface{} `json:"flags,omitempty"`
// Metadata is data we keep for the convenience of the caller. It is not
// expected to be large, since it is kept in memory.
Metadata string `json:"metadata,omitempty"`

// BigDataNames is a list of names of data items that we keep for the
// convenience of the caller. They can be large, and are only in
// memory when being read from or written to disk.
BigDataNames []string `json:"big-data-names,omitempty"`

Flags map[string]interface{} `json:"flags,omitempty"`
}

// ContainerStore provides bookkeeping for information about Containers.
Expand All @@ -44,11 +54,14 @@ type ContainerStore interface {
BigDataStore
FlaggableStore

// Create creates a container that has a specified ID (or a random one) and an
// optional name, based on the specified image, using the specified layer as
// its read-write layer.
// Create creates a container that has a specified ID (or generates a
// random one if an empty value is supplied) and optional names,
// based on the specified image, using the specified layer as its
// read-write layer.
Create(id string, names []string, image, layer, metadata string) (*Container, error)

// SetNames updates the list of names associated with the container
// with the specified ID.
SetNames(id string, names []string) error

// Get retrieves information about a container given an ID or name.
Expand Down
28 changes: 18 additions & 10 deletions storage/images.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,32 +18,40 @@ var (

// An Image is a reference to a layer and an associated metadata string.
type Image struct {
// ID is either one specified at import-time or a randomly-generated value.
// ID is either one which was specified at create-time, or a random
// value which was generated by the library.
ID string `json:"id"`

// Names is an optional set of user-defined convenience values.
// Names is an optional set of user-defined convenience values. The
// image can be referred to by its ID or any of its names. Names are
// unique among images.
Names []string `json:"names,omitempty"`

// TopLayer is the ID of the topmost layer of the image itself.
// Multiple images can refer to the same top layer.
TopLayer string `json:"layer"`

Metadata string `json:"metadata,omitempty"`
BigDataNames []string `json:"big-data-names,omitempty"`
Flags map[string]interface{} `json:"flags,omitempty"`
// Metadata is data we keep for the convenience of the caller. It is not
// expected to be large, since it is kept in memory.
Metadata string `json:"metadata,omitempty"`

// BigDataNames is a list of names of data items that we keep for the
// convenience of the caller. They can be large, and are only in
// memory when being read from or written to disk.
BigDataNames []string `json:"big-data-names,omitempty"`

Flags map[string]interface{} `json:"flags,omitempty"`
}

// ImageStore provides bookkeeping for information about Images.
//
//
//
type ImageStore interface {
FileBasedStore
MetadataStore
BigDataStore
FlaggableStore

// Create creates an image that has a specified ID (or a random one) and an
// optional name, using the specified layer as its topmost (hopefully
// Create creates an image that has a specified ID (or a random one) and
// optional names, using the specified layer as its topmost (hopefully
// read-only) layer. That layer can be referenced by multiple images.
Create(id string, names []string, layer, metadata string) (*Image, error)

Expand Down
33 changes: 23 additions & 10 deletions storage/layers.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,27 +34,37 @@ var (
// A Layer is a record of a copy-on-write layer that's stored by the lower
// level graph driver.
type Layer struct {
// ID is either one specified at import-time or a randomly-generated value.
// ID is either one which was specified at create-time, or a random
// value which was generated by the library.
ID string `json:"id"`

// Names is an optional set of user-defined convenience values.
// Names is an optional set of user-defined convenience values. The
// layer can be referred to by its ID or any of its names. Names are
// unique among layers.
Names []string `json:"names,omitempty"`

// Parent is the ID of a layer from which this layer inherits data.
Parent string `json:"parent,omitempty"`

// Metadata is data we keep for the convenience of the caller. It is not
// expected to be large, since it is kept in memory.
Metadata string `json:"metadata,omitempty"`

// MountLabel is an SELinux label which should be used when attempting to mount
// the layer.
MountLabel string `json:"mountlabel,omitempty"`

// MountPoint is the path where the layer is mounted, or where it was most
// recently mounted.
// recently mounted. This can change between subsequent Unmount() and
// Mount() calls, so the caller should consult this value after Mount()
// succeeds to find the location of the container's root filesystem.
MountPoint string `json:"-"`

MountCount int `json:"-"`
Flags map[string]interface{} `json:"flags,omitempty"`
// MountCount is used as a reference count for the container's layer being
// mounted at the mount point.
MountCount int `json:"-"`

Flags map[string]interface{} `json:"flags,omitempty"`
}

type layerMountPoint struct {
Expand All @@ -73,10 +83,11 @@ type LayerStore interface {

// Create creates a new layer, optionally giving it a specified ID rather than
// a randomly-generated one, either inheriting data from another specified
// layer or the empty base layer. The new layer can optionally be given a name
// layer or the empty base layer. The new layer can optionally be given names
// and have an SELinux label specified for use when mounting it. Some
// underlying drivers can accept a "size" option. At this time, drivers do not
// themselves distinguish between writeable and read-only layers.
// underlying drivers can accept a "size" option. At this time, most
// underlying drivers do not themselves distinguish between writeable
// and read-only layers.
Create(id, parent string, names []string, mountLabel string, options map[string]string, writeable bool) (*Layer, error)

// CreateWithFlags combines the functions of Create and SetFlag.
Expand All @@ -88,14 +99,15 @@ type LayerStore interface {
// Exists checks if a layer with the specified name or ID is known.
Exists(id string) bool

// Get retrieves information about a layer given an ID or name.
Get(id string) (*Layer, error)

// SetNames replaces the list of names associated with a layer with the
// supplied values.
SetNames(id string, names []string) error

// Status returns an slice of key-value pairs, suitable for human consumption,
// relaying whatever status information the driver can share.
// relaying whatever status information the underlying driver can share.
Status() ([][2]string, error)

// Delete deletes a layer with the specified name or ID.
Expand All @@ -120,7 +132,8 @@ type LayerStore interface {

// Diff produces a tarstream which can be applied to a layer with the contents
// of the first layer to produce a layer with the contents of the second layer.
// By default, the parent of the second layer is used as the first layer.
// By default, the parent of the second layer is used as the first
// layer, so it need not be specified.
Diff(from, to string) (io.ReadCloser, error)

// DiffSize produces an estimate of the length of the tarstream which would be
Expand Down
67 changes: 37 additions & 30 deletions storage/store.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,27 +113,29 @@ type Store interface {

// CreateLayer creates a new layer in the underlying storage driver, optionally
// having the specified ID (one will be assigned if none is specified), with
// the specified layer (or no layer) as its parent, and with an optional name.
// the specified layer (or no layer) as its parent, and with optional names.
// (The writeable flag is ignored.)
CreateLayer(id, parent string, names []string, mountLabel string, writeable bool) (*Layer, error)

// PutLayer combines the functions of CreateLayer and ApplyDiff, marking the
// layer for automatic removal if applying the diff fails for any reason.
PutLayer(id, parent string, names []string, mountLabel string, writeable bool, diff archive.Reader) (*Layer, error)

// CreateImage creates a new image, optionally with the specified ID (one will
// be assigned if none is specified), with an optional name, and referring to a
// specified image and with optional metadata. An image is a record which
// associates the ID of a layer with a caller-supplied metadata string which
// the library stores for the convenience of the caller.
// CreateImage creates a new image, optionally with the specified ID
// (one will be assigned if none is specified), with optional names,
// referring to a specified image, and with optional metadata. An
// image is a record which associates the ID of a layer with a
// additional bookkeeping information which the library stores for the
// convenience of its caller.
CreateImage(id string, names []string, layer, metadata string) (*Image, error)

// CreateContainer creates a new container, optionally with the specified ID
// (one will be assigned if none is specified), with an optional name, using
// the specified image's top layer as the basis for the container's layer, and
// assigning the specified ID to that layer (one will be created if none is
// specified). A container is a layer which is associated with a metadata
// string which the library stores for the convenience of the caller.
// (one will be assigned if none is specified), with optional names,
// using the specified image's top layer as the basis for the
// container's layer, and assigning the specified ID to that layer (one
// will be created if none is specified). A container is a layer which
// is associated with additional bookkeeping information which the
// library stores for the convenience of its caller.
CreateContainer(id string, names []string, image, layer, metadata string) (*Container, error)

// GetMetadata retrieves the metadata which is associated with a layer, image,
Expand Down Expand Up @@ -165,15 +167,16 @@ type Store interface {
// an error.
DeleteLayer(id string) error

// DeleteImage removes the specified image if it is not referred to by any
// containers. If its top layer is then no longer referred to by any other
// images or the parent of any other layers, its top layer will be removed. If
// that layer's parent is no longer referred to by any other images or the
// parent of any other layers, then it, too, will be removed. This procedure
// will be repeated until a layer which should not be removed, or the base
// layer, is reached, at which point the list of removed layers is returned.
// If the commit argument is false, the image and layers are not removed, but
// the list of layers which would be removed is still returned.
// DeleteImage removes the specified image if it is not referred to by
// any containers. If its top layer is then no longer referred to by
// any other images and is not the parent of any other layers, its top
// layer will be removed. If that layer's parent is no longer referred
// to by any other images and is not the parent of any other layers,
// then it, too, will be removed. This procedure will be repeated
// until a layer which should not be removed, or the base layer, is
// reached, at which point the list of removed layers is returned. If
// the commit argument is false, the image and layers are not removed,
// but the list of layers which would be removed is still returned.
DeleteImage(id string, commit bool) (layers []string, err error)

// DeleteContainer removes the specified container and its layer. If there is
Expand Down Expand Up @@ -259,8 +262,8 @@ type Store interface {
GetImage(id string) (*Image, error)

// GetImagesByTopLayer returns a list of images which reference the specified
// layer as their top layer. They will have different names and may have
// different metadata.
// layer as their top layer. They will have different IDs and names
// and may have different metadata, big data items, and flags.
GetImagesByTopLayer(id string) ([]*Image, error)

// GetContainer returns a specific container.
Expand All @@ -270,22 +273,26 @@ type Store interface {
// name.
GetContainerByLayer(id string) (*Container, error)

// GetContainerDirectory returns a path of a directory which the caller can use
// to store data which should be deleted when the container is deleted.
// GetContainerDirectory returns a path of a directory which the caller
// can use to store data, specific to the container, which the library
// does not directly manage. The directory will be deleted when the
// container is deleted.
GetContainerDirectory(id string) (string, error)

// GetContainerRunDirectory returns a path of a directory which the caller can
// use to store data about the container which should be deleted when the host
// system is restarted.
// GetContainerRunDirectory returns a path of a directory which the
// caller can use to store data, specific to the container, which the
// library does not directly manage. The directory will be deleted
// when the host system is restarted.
GetContainerRunDirectory(id string) (string, error)

// Lookup returns the ID of a layer, image, or container with the specified
// name.
// name or ID.
Lookup(name string) (string, error)

// Crawl enumerates all of the layers, images, and containers which depend on
// or refer to, either directly or indirectly, the specified layer, top layer
// of an image, or container layer.
// of an image, or container layer. This function is deprecated and
// will be removed.
Crawl(layerID string) (*Users, error)

// Version returns version information, in the form of key-value pairs, from
Expand All @@ -299,7 +306,7 @@ type Mall interface {
}

// Users holds an analysis of which layers, images, and containers depend on a
// given layer, either directly or indirectly.
// given layer, either directly or indirectly. This will be removed.
type Users struct {
ID string `json:"id"`
LayerID string `json:"layer"`
Expand Down

0 comments on commit d4ee4f6

Please sign in to comment.