Merge pull request #38117 from cpuguy83/volume_docstrings
Fix some doc strings in the volume package
This commit is contained in:
commit
22d3946d6c
|
@ -27,6 +27,7 @@ type volumeEventLogger interface {
|
||||||
}
|
}
|
||||||
|
|
||||||
// VolumesService manages access to volumes
|
// VolumesService manages access to volumes
|
||||||
|
// This is used as the main access point for volumes to higher level services and the API.
|
||||||
type VolumesService struct {
|
type VolumesService struct {
|
||||||
vs *VolumeStore
|
vs *VolumeStore
|
||||||
ds ds
|
ds ds
|
||||||
|
@ -54,6 +55,12 @@ func (s *VolumesService) GetDriverList() []string {
|
||||||
}
|
}
|
||||||
|
|
||||||
// Create creates a volume
|
// Create creates a volume
|
||||||
|
// If the caller is creating this volume to be consumed immediately, it is
|
||||||
|
// expected that the caller specifies a reference ID.
|
||||||
|
// This reference ID will protect this volume from removal.
|
||||||
|
//
|
||||||
|
// A good example for a reference ID is a container's ID.
|
||||||
|
// When whatever is going to reference this volume is removed the caller should defeference the volume by calling `Release`.
|
||||||
func (s *VolumesService) Create(ctx context.Context, name, driverName string, opts ...opts.CreateOption) (*types.Volume, error) {
|
func (s *VolumesService) Create(ctx context.Context, name, driverName string, opts ...opts.CreateOption) (*types.Volume, error) {
|
||||||
if name == "" {
|
if name == "" {
|
||||||
name = stringid.GenerateNonCryptoID()
|
name = stringid.GenerateNonCryptoID()
|
||||||
|
@ -68,7 +75,7 @@ func (s *VolumesService) Create(ctx context.Context, name, driverName string, op
|
||||||
return &apiV, nil
|
return &apiV, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// Get gets a volume
|
// Get returns details about a volume
|
||||||
func (s *VolumesService) Get(ctx context.Context, name string, getOpts ...opts.GetOption) (*types.Volume, error) {
|
func (s *VolumesService) Get(ctx context.Context, name string, getOpts ...opts.GetOption) (*types.Volume, error) {
|
||||||
v, err := s.vs.Get(ctx, name, getOpts...)
|
v, err := s.vs.Get(ctx, name, getOpts...)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
|
@ -88,6 +95,14 @@ func (s *VolumesService) Get(ctx context.Context, name string, getOpts ...opts.G
|
||||||
}
|
}
|
||||||
|
|
||||||
// Mount mounts the volume
|
// Mount mounts the volume
|
||||||
|
// Callers should specify a uniqe reference for each Mount/Unmount pair.
|
||||||
|
//
|
||||||
|
// Example:
|
||||||
|
// ```go
|
||||||
|
// mountID := "randomString"
|
||||||
|
// s.Mount(ctx, vol, mountID)
|
||||||
|
// s.Unmount(ctx, vol, mountID)
|
||||||
|
// ```
|
||||||
func (s *VolumesService) Mount(ctx context.Context, vol *types.Volume, ref string) (string, error) {
|
func (s *VolumesService) Mount(ctx context.Context, vol *types.Volume, ref string) (string, error) {
|
||||||
v, err := s.vs.Get(ctx, vol.Name, opts.WithGetDriver(vol.Driver))
|
v, err := s.vs.Get(ctx, vol.Name, opts.WithGetDriver(vol.Driver))
|
||||||
if err != nil {
|
if err != nil {
|
||||||
|
@ -101,6 +116,10 @@ func (s *VolumesService) Mount(ctx context.Context, vol *types.Volume, ref strin
|
||||||
|
|
||||||
// Unmount unmounts the volume.
|
// Unmount unmounts the volume.
|
||||||
// Note that depending on the implementation, the volume may still be mounted due to other resources using it.
|
// Note that depending on the implementation, the volume may still be mounted due to other resources using it.
|
||||||
|
//
|
||||||
|
// The reference specified here should be the same reference specified during `Mount` and should be
|
||||||
|
// unique for each mount/unmount pair.
|
||||||
|
// See `Mount` documentation for an example.
|
||||||
func (s *VolumesService) Unmount(ctx context.Context, vol *types.Volume, ref string) error {
|
func (s *VolumesService) Unmount(ctx context.Context, vol *types.Volume, ref string) error {
|
||||||
v, err := s.vs.Get(ctx, vol.Name, opts.WithGetDriver(vol.Driver))
|
v, err := s.vs.Get(ctx, vol.Name, opts.WithGetDriver(vol.Driver))
|
||||||
if err != nil {
|
if err != nil {
|
||||||
|
@ -118,6 +137,7 @@ func (s *VolumesService) Release(ctx context.Context, name string, ref string) e
|
||||||
}
|
}
|
||||||
|
|
||||||
// Remove removes a volume
|
// Remove removes a volume
|
||||||
|
// An error is returned if the volume is still referenced.
|
||||||
func (s *VolumesService) Remove(ctx context.Context, name string, rmOpts ...opts.RemoveOption) error {
|
func (s *VolumesService) Remove(ctx context.Context, name string, rmOpts ...opts.RemoveOption) error {
|
||||||
var cfg opts.RemoveConfig
|
var cfg opts.RemoveConfig
|
||||||
for _, o := range rmOpts {
|
for _, o := range rmOpts {
|
||||||
|
|
|
@ -182,7 +182,7 @@ func (s *VolumeStore) purge(ctx context.Context, name string) error {
|
||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// VolumeStore is a struct that stores the list of volumes available and keeps track of their usage counts
|
// VolumeStore is responsible for storing and reference counting volumes.
|
||||||
type VolumeStore struct {
|
type VolumeStore struct {
|
||||||
// locks ensures that only one action is being performed on a particular volume at a time without locking the entire store
|
// locks ensures that only one action is being performed on a particular volume at a time without locking the entire store
|
||||||
// since actions on volumes can be quite slow, this ensures the store is free to handle requests for other volumes.
|
// since actions on volumes can be quite slow, this ensures the store is free to handle requests for other volumes.
|
||||||
|
|
Loading…
Reference in New Issue