From b03ddd1d4c2f10ce067ad5866da4e3dc9a83f869 Mon Sep 17 00:00:00 2001 From: Marius Date: Fri, 18 Dec 2015 23:13:00 +0100 Subject: [PATCH] Add documentation for package lockingstore --- lockingstore/lockingstore.go | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/lockingstore/lockingstore.go b/lockingstore/lockingstore.go index ca59c89..13019af 100644 --- a/lockingstore/lockingstore.go +++ b/lockingstore/lockingstore.go @@ -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 import ( @@ -6,13 +15,30 @@ import ( "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 { + // 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 + // UnlockUpload releases an existing lock for the given upload. 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 { + // The underlying data storage to which the operation will be passed if an + // upload is not locked. tusd.DataStore + // The custom locking persisting mechanism used for obtaining and releasing + // locks. Locker Locker }