Skip to content

storage: fix up docstring comments #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
cyphar wants to merge 1 commit into from
Closed

storage: fix up docstring comments #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 32 additions & 32 deletions storage/containers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,57 +17,57 @@ var (
)

// A Container is a reference to a read-write layer with a metadata string.
// ID is either one specified at create-time or a randomly-generated value.
// Names is an optional set of user-defined convenience values.
// ImageID is the ID of the image which was used to create the container.
// LayerID is the ID of the read-write layer for the container itself.
// It is assumed that the image's top layer is the parent of the container's
// read-write layer.
type Container struct {
ID string `json:"id"`
Names []string `json:"names,omitempty"`
ImageID string `json:"image"`
LayerID string `json:"layer"`
// ID is either one specified at create-time or a randomly-generated value.
ID string `json:"id"`

// Names is an optional set of user-defined convenience values.
Names []string `json:"names,omitempty"`

// ImageID is the ID of the image which was used to create the container.
ImageID string `json:"image"`

// LayerID is the ID of the read-write layer for the container itself.
// It is assumed that the image's top layer is the parent of the container's
// 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"`
}

// ContainerStore provides bookkeeping for information about Containers.
//
// 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.
//
// GetMetadata retrieves a container's metadata.
//
// SetMetadata replaces the metadata associated with a container with the
// supplied value.
//
// Exists checks if there is a container with the given ID or name.
//
// Get retrieves information about a container given an ID or name.
//
// Delete removes the record of the container.
//
// Wipe removes records of all containers.
//
// Lookup attempts to translate a name to an ID. Most methods do this
// implicitly.
//
// Containers returns a slice enumerating the known containers.
type ContainerStore interface {
FileBasedStore
MetadataStore
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(id string, names []string, image, layer, metadata string) (*Container, error)

SetNames(id string, names []string) error

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

// Exists checks if there is a container with the given ID or name.
Exists(id string) bool

// Delete removes the record of the container.
Delete(id string) error

// Wipe removes records of all containers.
Wipe() error

// Lookup attempts to translate a name to an ID. Most methods do this
// implicitly.
Lookup(name string) (string, error)

// Containers returns a slice enumerating the known containers.
Containers() ([]Container, error)
}

Expand Down
57 changes: 29 additions & 28 deletions storage/images.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,56 +17,57 @@ var (
)

// An Image is a reference to a layer and an associated metadata string.
// ID is either one specified at import-time or a randomly-generated value.
// Names is an optional set of user-defined convenience values.
// TopLayer is the ID of the topmost layer of the image itself.
type Image struct {
ID string `json:"id"`
Names []string `json:"names,omitempty"`
TopLayer string `json:"layer"`
// ID is either one specified at import-time or a randomly-generated value.
ID string `json:"id"`

// Names is an optional set of user-defined convenience values.
Names []string `json:"names,omitempty"`

// TopLayer is the ID of the topmost layer of the image itself.
TopLayer string `json:"layer"`

Metadata string `json:"metadata,omitempty"`
BigDataNames []string `json:"big-data-names,omitempty"`
Flags map[string]interface{} `json:"flags,omitempty"`
}

// ImageStore provides bookkeeping for information about Images.
//
// 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
// read-only) layer. That layer can be referenced by multiple images.
//
// GetMetadata retrieves an image's metadata.
//
// SetMetadata replaces the metadata associated with an image with the supplied
// value.
//
// SetNames replaces the list of names associated with an image with the
// supplied values.
//
// Exists checks if there is an image with the given ID or name.
//
// Get retrieves information about an image given an ID or name.
//
// Delete removes the record of the image.
//
// Wipe removes records of all images.
//
// Lookup attempts to translate a name to an ID. Most methods do this
// implicitly.
//
// Images returns a slice enumerating the known 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
// read-only) layer. That layer can be referenced by multiple images.
Create(id string, names []string, layer, metadata string) (*Image, error)

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

// Exists checks if there is an image with the given ID or name.
Exists(id string) bool

// Get retrieves information about an image given an ID or name.
Get(id string) (*Image, error)

// Delete removes the record of the image.
Delete(id string) error

// Wipe removes records of all images.
Wipe() error

// Lookup attempts to translate a name to an ID. Most methods do this
// implicitly.
Lookup(name string) (string, error)

// Images returns a slice enumerating the known images.
Images() ([]Image, error)
}

Expand Down
135 changes: 69 additions & 66 deletions storage/layers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,19 +33,26 @@ var (

// A Layer is a record of a copy-on-write layer that's stored by the lower
// level graph driver.
// ID is either one specified at import-time or a randomly-generated value.
// Names is an optional set of user-defined convenience values. Parent is the
// ID of a layer from which this layer inherits data. MountLabel is an SELinux
// label which should be used when attempting to mount the layer. MountPoint
// is the path where the layer is mounted, or where it was most recently
// mounted.
type Layer struct {
ID string `json:"id"`
Names []string `json:"names,omitempty"`
Parent string `json:"parent,omitempty"`
Metadata string `json:"metadata,omitempty"`
MountLabel string `json:"mountlabel,omitempty"`
MountPoint string `json:"-"`
// ID is either one specified at import-time or a randomly-generated value.
ID string `json:"id"`

// Names is an optional set of user-defined convenience values.
Names []string `json:"names,omitempty"`

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

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.
MountPoint string `json:"-"`

MountCount int `json:"-"`
Flags map[string]interface{} `json:"flags,omitempty"`
}
Expand All @@ -59,80 +66,76 @@ type layerMountPoint struct {
// LayerStore wraps a graph driver, adding the ability to refer to layers by
// name, and keeping track of parent-child relationships, along with a list of
// all known layers.
//
// 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
// 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.
//
// CreateWithFlags combines the functions of Create and SetFlag.
//
// Put combines the functions of CreateWithFlags and ApplyDiff.
//
// Exists checks if a layer with the specified name or ID is known.
//
// GetMetadata retrieves a layer's metadata.
//
// SetMetadata replaces the metadata associated with a layer with the supplied
// value.
//
// SetNames replaces the list of names associated with a layer with the
// supplied values.
//
// Status returns an slice of key-value pairs, suitable for human consumption,
// relaying whatever status information the driver can share.
//
// Delete deletes a layer with the specified name or ID.
//
// Wipe deletes all layers.
//
// Mount mounts a layer for use. If the specified layer is the parent of other
// layers, it should not be written to. An SELinux label to be applied to the
// mount can be specified to override the one configured for the layer.
//
// Unmount unmounts a layer when it is no longer in use.
//
// Changes returns a slice of Change structures, which contain a pathname
// (Path) and a description of what sort of change (Kind) was made by the
// layer (either ChangeModify, ChangeAdd, or ChangeDelete), relative to a
// specified layer. By default, the layer's parent is used as a reference.
//
// 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.
//
// DiffSize produces an estimate of the length of the tarstream which would be
// produced by Diff.
//
// ApplyDiff reads a tarstream which was created by a previous call to Diff and
// applies its changes to a specified layer.
//
// Lookup attempts to translate a name to an ID. Most methods do this
// implicitly.
//
// Layers returns a slice of the known layers.
type LayerStore interface {
FileBasedStore
MetadataStore
FlaggableStore

// 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
// 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.
Create(id, parent string, names []string, mountLabel string, options map[string]string, writeable bool) (*Layer, error)

// CreateWithFlags combines the functions of Create and SetFlag.
CreateWithFlags(id, parent string, names []string, mountLabel string, options map[string]string, writeable bool, flags map[string]interface{}) (layer *Layer, err error)

// Put combines the functions of CreateWithFlags and ApplyDiff.
Put(id, parent string, names []string, mountLabel string, options map[string]string, writeable bool, flags map[string]interface{}, diff archive.Reader) (layer *Layer, err error)

// Exists checks if a layer with the specified name or ID is known.
Exists(id string) bool

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.
Status() ([][2]string, error)

// Delete deletes a layer with the specified name or ID.
Delete(id string) error

// Wipe deletes all layers.
Wipe() error

// Mount mounts a layer for use. If the specified layer is the parent of other
// layers, it should not be written to. An SELinux label to be applied to the
// mount can be specified to override the one configured for the layer.
Mount(id, mountLabel string) (string, error)

// Unmount unmounts a layer when it is no longer in use.
Unmount(id string) error

// Changes returns a slice of Change structures, which contain a pathname
// (Path) and a description of what sort of change (Kind) was made by the
// layer (either ChangeModify, ChangeAdd, or ChangeDelete), relative to a
// specified layer. By default, the layer's parent is used as a reference.
Changes(from, to string) ([]archive.Change, error)

// 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.
Diff(from, to string) (io.ReadCloser, error)

// DiffSize produces an estimate of the length of the tarstream which would be
// produced by Diff.
DiffSize(from, to string) (int64, error)

// ApplyDiff reads a tarstream which was created by a previous call to Diff and
// applies its changes to a specified layer.
ApplyDiff(to string, diff archive.Reader) (int64, error)

// Lookup attempts to translate a name to an ID. Most methods do this
// implicitly.
Lookup(name string) (string, error)

// Layers returns a slice of the known layers.
Layers() ([]Layer, error)
}

Expand Down
12 changes: 6 additions & 6 deletions storage/lockfile.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ import (
// A Locker represents a file lock where the file is used to cache an
// identifier of the last party that made changes to whatever's being protected
// by the lock.
//
// Touch() records, for others sharing the lock, that it was updated by the
// caller. It should only be called with the lock held.
//
// Modified() checks if the most recent writer was a party other than the
// caller. It should only be called with the lock held.
type Locker interface {
sync.Locker

// Touch records, for others sharing the lock, that it was updated by the
// caller. It should only be called with the lock held.
Touch() error

// Modified() checks if the most recent writer was a party other than the
// caller. It should only be called with the lock held.
Modified() (bool, error)
}

Expand Down
Loading