From 1c2f5fe203823fcb8285180b40166b287ee4daf6 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Tue, 4 Apr 2017 13:31:38 -0700 Subject: [PATCH] Update documentation to storage package Signed-off-by: Derek McGowan --- snapshot/storage/bolt.go | 8 ++++++-- snapshot/storage/metastore.go | 17 ++++++++++++++--- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/snapshot/storage/bolt.go b/snapshot/storage/bolt.go index a3e7a10..455f760 100644 --- a/snapshot/storage/bolt.go +++ b/snapshot/storage/bolt.go @@ -16,6 +16,10 @@ var ( bucketKeyStorageVersion = []byte("v1") bucketKeySnapshot = []byte("snapshots") bucketKeyParents = []byte("parents") + + // ErrNoTransaction is returned when an operation is attempted with + // a context which is not inside of a transaction. + ErrNoTransaction = errors.New("no transaction in context") ) type boltFileTransactor struct { @@ -301,7 +305,7 @@ func CommitActive(ctx context.Context, key, name string) (id string, err error) func withBucket(ctx context.Context, fn func(context.Context, *bolt.Bucket, *bolt.Bucket) error) error { t, ok := ctx.Value(transactionKey{}).(*boltFileTransactor) if !ok { - return errors.Errorf("no transaction in context") + return ErrNoTransaction } bkt := t.tx.Bucket(bucketKeyStorageVersion) if bkt == nil { @@ -313,7 +317,7 @@ func withBucket(ctx context.Context, fn func(context.Context, *bolt.Bucket, *bol func createBucketIfNotExists(ctx context.Context, fn func(context.Context, *bolt.Bucket, *bolt.Bucket) error) error { t, ok := ctx.Value(transactionKey{}).(*boltFileTransactor) if !ok { - return errors.Errorf("no transaction in context") + return ErrNoTransaction } bkt, err := t.tx.CreateBucketIfNotExists(bucketKeyStorageVersion) diff --git a/snapshot/storage/metastore.go b/snapshot/storage/metastore.go index f1d3218..c223d40 100644 --- a/snapshot/storage/metastore.go +++ b/snapshot/storage/metastore.go @@ -1,3 +1,8 @@ +// Package storage provides a metadata storage implementation for snapshot +// drivers. Drive implementations are responsible for starting and managing +// transactions using the defined context creator. This storage package uses +// BoltDB for storing metadata. Access to the raw boltdb transaction is not +// provided, but the stored object is provided by the proto subpackage. package storage import ( @@ -9,10 +14,15 @@ import ( // Transactor is used to finalize an active transaction. type Transactor interface { - // Commit commits any changes made during the transaction. + // Commit commits any changes made during the transaction. On error a + // caller is expected to clean up any resources which would have relied + // on data mutated as part of this transaction. Only writable + // transactions can commit, non-writable must call Rollback. Commit() error - // Rollback rolls back any changes made during the transaction. + // Rollback rolls back any changes made during the transaction. This + // must be called on all non-writable transactions and aborted writable + // transaction. Rollback() error } @@ -48,7 +58,8 @@ func NewMetaStore(dbfile string) (*MetaStore, error) { type transactionKey struct{} -// TransactionContext creates a new transaction context. +// TransactionContext creates a new transaction context. The writable value +// should be set to true for transactions which are expected to mutate data. func (ms *MetaStore) TransactionContext(ctx context.Context, writable bool) (context.Context, Transactor, error) { db, err := bolt.Open(ms.dbfile, 0600, nil) if err != nil {