Add interface for libpod multiprocess locks

Signed-off-by: Matthew Heon <matthew.heon@gmail.com>

1 files changed, 55 insertions, 0 deletions

diff --git a/libpod/lock/lock.go b/libpod/lock/lock.go
new file mode 100644
index 000000000..6999e1118
--- /dev/null
+++ b/libpod/lock/lock.go
@@ -0,0 +1,55 @@
+package lock
+
+// LockManager provides an interface for allocating multiprocess locks.
+// Locks returned by LockManager MUST be multiprocess - allocating a lock in
+// process A and retrieving that lock's ID in process B must return handles for
+// the same lock, and locking the lock in A should exclude B from the lock until
+// it is unlocked in A.
+// All locks must be identified by a UUID (retrieved with Locker's ID() method).
+// All locks with a given UUID must refer to the same underlying lock, and it
+// must be possible to retrieve the lock given its UUID.
+// Each UUID should refer to a unique underlying lock.
+// Calls to AllocateLock() must return a unique, unallocated UUID.
+// AllocateLock() must fail once all available locks have been allocated.
+// Locks are returned to use by calls to Free(), and can subsequently be
+// reallocated.
+type LockManager interface {
+	// AllocateLock returns an unallocated lock.
+	// It is guaranteed that the same lock will not be returned again by
+	// AllocateLock until the returned lock has Free() called on it.
+	// If all available locks are allocated, AllocateLock will return an
+	// error.
+	AllocateLock() (Locker, error)
+	// RetrieveLock retrieves a lock given its UUID.
+	// The underlying lock MUST be the same as another other lock with the
+	// same UUID.
+	RetrieveLock(id string) (Locker, error)
+}
+
+// Locker is similar to sync.Locker, but provides a method for freeing the lock
+// to allow its reuse.
+// All Locker implementations must maintain mutex semantics - the lock only
+// allows one caller in the critical section at a time.
+// All locks with the same ID must refer to the same underlying lock, even
+// if they are within multiple processes.
+type Locker interface {
+	// ID retrieves the lock's ID.
+	// ID is guaranteed to uniquely identify the lock within the
+	// LockManager - that is, calling RetrieveLock with this ID will return
+	// another instance of the same lock.
+	ID() string
+	// Lock locks the lock.
+	// This call MUST block until it successfully acquires the lock or
+	// encounters a fatal error.
+	Lock() error
+	// Unlock unlocks the lock.
+	// A call to Unlock() on a lock that is already unlocked lock MUST
+	// error.
+	Unlock() error
+	// Deallocate deallocates the underlying lock, allowing its reuse by
+	// other pods and containers.
+	// The lock MUST still be usable after a Free() - some libpod instances
+	// may still retain Container structs with the old lock. This simply
+	// advises the manager that the lock may be reallocated.
+	Free() error
+}