README
¶
go-gcslock
GCS Lock creates a forward-looking lock using Google Cloud Storage. The lock is forward-looking because it is not actually "held" like a mutex. This is useful in situations where you want something to occur at most once over a duration, but multiple independent processes could trigger the event.
"Identity" is tied to the object itself; different locks should use different object names.
Usage
lock, err := gcslock.New(ctx, "my-bucket", "my-object")
if err != nil {
panic(err) // TODO: handle error
}
defer lock.Close(ctx)
// Acquire the lock for 30 minutes. Upon successful return from this method,
// the lock is held.
if err := lock.Acquire(ctx, 30*time.Minute); err != nil {
var lockErr *ErrLockHeld
if errors.As(err, &lockErr) {
// Lock is already held
log.Printf("lock is held until %s", lockErr.NotBefore())
}
panic(err) // TODO: handle error
}
Documentation
¶
Overview ¶
Package gcslock acquires a forward-looking lock leveraging a file in a Google Cloud Storage bucket. Unlike a mutex, the lock is TTL-based instead of "held" like a traditional mutex.
Compared to other mutexes, this is intended to be a long-lived lock. The minimum granularity is "seconds" and most consumers will acquire a lock for "minutes" or "hours". Because of clock skew and network latency, granularity below 1s is not a supported use case.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GCSLock ¶
type GCSLock struct {
// contains filtered or unexported fields
}
GCSLock represents a remote forward-looking lock in Google Cloud Storage.
func New ¶
New creates a new distributed locking handler on the specific object in Google Cloud. It does create the lock until Acquire is called.
func (*GCSLock) Acquire ¶
Acquire attempts to acquire the lock. It returns [ErrLockHeld] if the lock is already held. Callers can cast the error type to get more specific information like the TTL expiration time:
if err := lock.Acquire(ctx, 5*time.Minute); err != nil {
var lockErr *ErrLockHeld
if errors.As(err, &lockErr) {
log.Printf("lock is held until %s", lockErr.NotBefore())
}
}
It automatically retries transient upstream API errors, but returns immediately for errors that are irrecoverable.
type GCSLocker ¶ added in v0.1.1
type GCSLocker interface {
New(ctx context.Context, bucket, object string, opts ...option.ClientOption) (*GCSLock, error)
Acquire(ctx context.Context, ttl time.Duration) error
Close(ctx context.Context) error
}
GCSLocker is the interface that defines how to manage a lock with GCS.
type LockHeldError ¶
type LockHeldError struct {
// contains filtered or unexported fields
}
LockHeldError is a specific error returned when a lock is alread held.
func (*LockHeldError) Error ¶
func (e *LockHeldError) Error() string
Error implements the error interface.
func (*LockHeldError) Is ¶
func (e *LockHeldError) Is(err error) bool
Is implements the error comparison interface.
func (*LockHeldError) NotBefore ¶
func (e *LockHeldError) NotBefore() time.Time
NotBefore returns the UTC Unix timestamp of when the lock expires.
Source Files