Add documentation for package lockingstore

This commit is contained in:
Marius 2015-12-18 23:13:00 +01:00
parent 4073f4ae64
commit b03ddd1d4c
1 changed files with 26 additions and 0 deletions

View File

@ -1,3 +1,12 @@
// Package lockingstore manages concurrent access to a single upload.
//
// When multiple processes are attempting to access an upload, whether it be
// by reading or writing, a syncronization mechanism is required to prevent
// data corruption, especially to ensure correct offset values and the proper
// order of chunks inside a single upload.
//
// This package wrappes an existing data storage and only allows a single access
// at a time by using an exclusive locking mechanism.
package lockingstore package lockingstore
import ( import (
@ -6,13 +15,30 @@ import (
"github.com/tus/tusd" "github.com/tus/tusd"
) )
// Locker is the interface required for custom lock persisting mechanisms.
// Common ways to store this information is in memory, on disk or using an
// external service, such as ZooKeeper.
type Locker interface { type Locker interface {
// LockUpload attempts to obtain an exclusive lock for the upload specified
// by its id.
// If this operation fails because the resource is already locked, the
// tusd.ErrFileLocked must be returned. If no error is returned, the attempt
// is consider to be successful and the upload to be locked until UnlockUpload
// is invoked for the same upload.
LockUpload(id string) error LockUpload(id string) error
// UnlockUpload releases an existing lock for the given upload.
UnlockUpload(id string) error UnlockUpload(id string) error
} }
// LockingStore wraps an existing data storage and catches all operation.
// Before passing the method calls to the underlying backend, locks are required
// to be obtained.
type LockingStore struct { type LockingStore struct {
// The underlying data storage to which the operation will be passed if an
// upload is not locked.
tusd.DataStore tusd.DataStore
// The custom locking persisting mechanism used for obtaining and releasing
// locks.
Locker Locker Locker Locker
} }