Add documentation for how to register new StorageDrivers
This commit adds context-specific documentation on StorageDriver, StorageDriverFactory, and the factory’s Register func, explaining how the internal registration mechanism should be used. This documentation follows from the thread starting at https://github.com/deis/builder/pull/262/files#r56720200. cc/ @stevvooe Signed-off-by: Aaron Schlesinger <aschlesinger@deis.com>
This commit is contained in:
parent
0ef5587b76
commit
0f09bcd16a
2 changed files with 18 additions and 2 deletions
|
@ -11,7 +11,14 @@ import (
|
||||||
var driverFactories = make(map[string]StorageDriverFactory)
|
var driverFactories = make(map[string]StorageDriverFactory)
|
||||||
|
|
||||||
// StorageDriverFactory is a factory interface for creating storagedriver.StorageDriver interfaces
|
// StorageDriverFactory is a factory interface for creating storagedriver.StorageDriver interfaces
|
||||||
// Storage drivers should call Register() with a factory to make the driver available by name
|
// Storage drivers should call Register() with a factory to make the driver available by name.
|
||||||
|
// Individual StorageDriver implementations generally register with the factory via the Register
|
||||||
|
// func (below) in their init() funcs, and as such they should be imported anonymously before use.
|
||||||
|
// See below for an example of how to register and get a StorageDriver for S3
|
||||||
|
//
|
||||||
|
// import _ "github.com/docker/distribution/registry/storage/driver/s3-aws"
|
||||||
|
// s3Driver, err = factory.Create("s3", storageParams)
|
||||||
|
// // assuming no error, s3Driver is the StorageDriver that communicates with S3 according to storageParams
|
||||||
type StorageDriverFactory interface {
|
type StorageDriverFactory interface {
|
||||||
// Create returns a new storagedriver.StorageDriver with the given parameters
|
// Create returns a new storagedriver.StorageDriver with the given parameters
|
||||||
// Parameters will vary by driver and may be ignored
|
// Parameters will vary by driver and may be ignored
|
||||||
|
@ -21,6 +28,8 @@ type StorageDriverFactory interface {
|
||||||
|
|
||||||
// Register makes a storage driver available by the provided name.
|
// Register makes a storage driver available by the provided name.
|
||||||
// If Register is called twice with the same name or if driver factory is nil, it panics.
|
// If Register is called twice with the same name or if driver factory is nil, it panics.
|
||||||
|
// Additionally, it is not concurrency safe. Most Storage Drivers call this function
|
||||||
|
// in their init() functions. See the documentation for StorageDriverFactory for more.
|
||||||
func Register(name string, factory StorageDriverFactory) {
|
func Register(name string, factory StorageDriverFactory) {
|
||||||
if factory == nil {
|
if factory == nil {
|
||||||
panic("Must not provide nil StorageDriverFactory")
|
panic("Must not provide nil StorageDriverFactory")
|
||||||
|
|
|
@ -34,7 +34,14 @@ func (version Version) Minor() uint {
|
||||||
const CurrentVersion Version = "0.1"
|
const CurrentVersion Version = "0.1"
|
||||||
|
|
||||||
// StorageDriver defines methods that a Storage Driver must implement for a
|
// StorageDriver defines methods that a Storage Driver must implement for a
|
||||||
// filesystem-like key/value object storage.
|
// filesystem-like key/value object storage. Storage Drivers are automatically
|
||||||
|
// registered via an internal registration mechanism, and generally created
|
||||||
|
// via the StorageDriverFactory interface (https://godoc.org/github.com/docker/distribution/registry/storage/driver/factory).
|
||||||
|
// See below for an example of how to get a StorageDriver for S3:
|
||||||
|
//
|
||||||
|
// import _ "github.com/docker/distribution/registry/storage/driver/s3-aws"
|
||||||
|
// s3Driver, err = factory.Create("s3", storageParams)
|
||||||
|
// // assuming no error, s3Driver is the StorageDriver that communicates with S3 according to storageParams
|
||||||
type StorageDriver interface {
|
type StorageDriver interface {
|
||||||
// Name returns the human-readable "name" of the driver, useful in error
|
// Name returns the human-readable "name" of the driver, useful in error
|
||||||
// messages and logging. By convention, this will just be the registration
|
// messages and logging. By convention, this will just be the registration
|
||||||
|
|
Loading…
Reference in a new issue