README
¶
A global mutex using Google Cloud Storage
Based on “A robust distributed locking algorithm based on Google Cloud Storage” and github.com/marcacohen/gcslock.
Documentation
¶
Overview ¶
Package gmutex implements a global mutex using Google Cloud Storage.
Index ¶
- Variables
- type Mutex
- func (m *Mutex) Abandon() string
- func (m *Mutex) Adopt(ctx context.Context, id string) error
- func (m *Mutex) AdoptData(ctx context.Context, id string, data io.Reader) error
- func (m *Mutex) AdoptJSON(ctx context.Context, id string, v any) error
- func (m *Mutex) Extend(ctx context.Context) error
- func (m *Mutex) InspectData(ctx context.Context, data io.Writer) (bool, error)
- func (m *Mutex) InspectJSON(ctx context.Context, v any) (bool, error)
- func (m *Mutex) Lock(ctx context.Context) error
- func (m *Mutex) LockData(ctx context.Context, data io.Reader) error
- func (m *Mutex) LockJSON(ctx context.Context, v any) error
- func (m *Mutex) Locker() sync.Locker
- func (m *Mutex) SetTTL(ttl time.Duration)
- func (m *Mutex) TTL() time.Duration
- func (m *Mutex) TryLock(ctx context.Context) (bool, error)
- func (m *Mutex) TryLockData(ctx context.Context, data io.Reader) (bool, error)
- func (m *Mutex) TryLockJSON(ctx context.Context, v any) (bool, error)
- func (m *Mutex) Unlock(ctx context.Context) error
- func (m *Mutex) UpdateData(ctx context.Context, data io.Reader) error
- func (m *Mutex) UpdateJSON(ctx context.Context, v any) error
Constants ¶
This section is empty.
Variables ¶
var HTTPClient *http.Client
HTTPClient should be set to an http.Client before first use. If unset google.DefaultClient will be used.
Functions ¶
This section is empty.
Types ¶
type Mutex ¶
type Mutex struct {
// contains filtered or unexported fields
}
A Mutex is a global, mutual exclusion lock that uses an object in Google Cloud Storage to serialize computations across the internet.
A Mutex can optionally have data attached to it while it is held. While there is no limit to the size of this data, it is best kept small. Provided data must be of type *bytes.Buffer, *bytes.Reader, or *strings.Reader.
Given the latency and scalability properties of Google Cloud Storage, a Mutex is best used to serialize long-running, high-latency compute processes. Critical sections should span seconds. Expect an uncontended mutex to take tens to hundreds of milliseconds to acquire, and a contended one multiple seconds after release.
An instance of Mutex is not associated with a particular goroutine (it is allowed for one goroutine to lock a Mutex and then arrange for another goroutine to unlock it), but it is not safe for concurrent use by multiple goroutines.
To use an API-compatible alternative to Google Cloud Storage (such as fake-gcs-server or similar), provide the endpoint by setting the environment variable STORAGE_EMULATOR_HOST prior to creating the Mutex.
func New ¶ added in v0.5.3
New creates a new Mutex at the given bucket and object, with the given time-to-live.
func (*Mutex) Abandon ¶ added in v0.6.0
Abandon abandons m, returning a lock id that can be used to call Adopt.
func (*Mutex) Adopt ¶ added in v0.6.0
Adopt adopts an abandoned lock into m, and calls Extend to ensure mutual exclusion.
func (*Mutex) AdoptData ¶ added in v0.6.0
AdoptData adopts an abandoned lock into m, and calls UpdateData to ensure mutual exclusion.
func (*Mutex) Extend ¶ added in v0.6.1
Extend extends the expiration time of m, keeping any attached data. Returns an error if the lock has already expired, and mutual exclusion can not be ensured.
func (*Mutex) InspectData ¶ added in v0.7.0
InspectData inspects m, returning its locked state and fetching attached data.
func (*Mutex) InspectJSON ¶ added in v0.6.8
InspectJSON calls InspectData. Parses JSON-encoded data into the value pointed to by v.
func (*Mutex) Lock ¶
Lock locks m. If the lock is already in use, the calling goroutine blocks until the mutex is available, or the context expires. Returns nil if the lock was taken successfully.
func (*Mutex) LockData ¶ added in v0.6.0
LockData locks m with attached data. If the lock is already in use, the calling goroutine blocks until the mutex is available, or the context expires. Returns nil if the lock was taken successfully (and the attached data stored).
func (*Mutex) Locker ¶ added in v0.5.3
Locker gets a Locker that uses context.Background to call Lock and Unlock, and panics on error.
func (*Mutex) SetTTL ¶ added in v0.6.3
SetTTL sets the time-to-live to use when the mutex is locked, extended, or updated. The time-to-live is rounded up to the nearest second. Negative or zero time-to-live means the lock never expires.
func (*Mutex) TTL ¶ added in v0.6.3
TTL gets the time-to-live to use when the mutex is locked, extended, or updated.
func (*Mutex) TryLock ¶ added in v0.6.0
TryLock tries to lock m. Returns true if the lock was taken successfully, false if the lock is already in use.
func (*Mutex) TryLockData ¶ added in v0.6.0
TryLockData tries to lock m with attached data. Returns true if the lock was taken successfully (and the attached data stored). Returns false if the lock is already in use, fetching attached data if data satisfies io.Writer.
func (*Mutex) TryLockJSON ¶ added in v0.6.8
TryLockJSON calls TryLockData with the JSON encoding of v. Parses JSON-encoded data into the value pointed to by v, if the lock is already in use and v is a pointer.
func (*Mutex) Unlock ¶
Unlock unlocks m, deleting any attached data. Returns an error if the lock had already expired, and mutual exclusion was not ensured.
func (*Mutex) UpdateData ¶ added in v0.7.0
UpdateData updates attached data, extending the expiration time of m. Returns an error if the lock has already expired, and mutual exclusion can not be ensured.
Source Files