Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Locker ¶
type Locker struct {
// contains filtered or unexported fields
}
Locker is a distributed lock.
It is a renewable distributed lock built on memcached: each lock maps to one memcached key and its ownership is defined by an independent version identifier. While the lock is held its expiration is refreshed through a "read-verify-CAS" loop, and the lock becomes invalid once it expires or its ownership is lost.
func (*Locker) Acquire ¶
Acquire acquires the lock.
Acquire blocks until the lock is acquired, after which it starts a background renewal to keep holding the lock until it is explicitly released or lost. The ctx is the context whose cancellation aborts the acquisition. It returns nil on success, errors.ErrDeadlineExceeded when the retries are exhausted, or ctx.Err() when the context is canceled.
func (*Locker) Release ¶
Release releases the lock.
Release stops the background renewal first and then releases the lock by version identifier; only the owner of the lock (a matching version identifier) can release it successfully. The ctx is the context to use. It returns nil on success, errors.ErrIllegalOperation when the lock has been lost or its ownership has changed, or the driver error on a persistent CAS conflict (a transient race).
func (*Locker) TryAcquire ¶
TryAcquire attempts to acquire the lock.
TryAcquire makes a single attempt and returns immediately on failure without blocking. On success, a positive expiration makes the lock expire once after that duration without renewal; otherwise the lock uses the default expiration and starts a background renewal. The ctx is the context to use. The optional expiration is a fixed expiration time; when it is empty or not positive, the lock is not time-bounded and renewal is enabled. It returns nil on success or errors.ErrIllegalOperation when the lock is already held by someone else.
type Maker ¶
type Maker struct {
// contains filtered or unexported fields
}
Maker is a lock maker.
It creates distributed locks from the memcached Add/Get/CompareAndSwap primitives. It holds the memcached client and the global lock configuration internally, and generates an independent version identifier for each lock to verify lock ownership.
func NewMaker ¶
NewMaker creates a lock maker.
It initializes the lock configuration: when the expiration is not explicitly configured the default value is used, and an expiration below 1 second is clamped to 1 second so that memcached does not truncate a sub-second expiration to 0 (never expires). An acquisition interval of 0 or less is clamped to the default so that the retry loop does not degenerate into a busy-wait without backoff. When no external client is provided, a built-in client is created automatically and is closed along with Close.
func (*Maker) Close ¶
Close closes the maker.
It first cancels the maker lifecycle context to stop every background renewal goroutine, then closes the built-in client. When an external client is used, its lifecycle is managed by the external caller and is left untouched here.
type Option ¶
type Option func(o *options)
Option is a lock configuration function.
func WithAcquireInterval ¶
WithAcquireInterval sets the interval between lock acquisition attempts.
It is the interval between retries after a failed lock acquisition; a value of 0 or less is clamped to the default 20ms in NewMaker.
func WithAcquireMaxRetries ¶
WithAcquireMaxRetries sets the maximum number of lock acquisition retries.
When the maximum number of retries is reached without acquiring the lock, a timeout error is returned; 0 means unlimited retries until success or context cancellation.
func WithAddrs ¶
WithAddrs sets the client connection addresses.
It sets the connection addresses of the built-in client and takes effect only when no external client is specified.
func WithClient ¶
WithClient sets an external client.
It sets an external client, which is preferred when present; in that case the Maker no longer manages the client's lifecycle when it is closed.
func WithExpiration ¶
WithExpiration sets the lock expiration.
It sets the expiration of the lock, which is also the target duration refreshed by the background renewal. memcached has second granularity, so a value below 1s is clamped to 1s. Note: memcached records the expiration in whole seconds, so the actual lifetime may be nearly one second shorter than the configured value. The background renewal interval is half of the expiration, so an expiration below 2s may make it hard for the renewal to finish before the lock expires; for a renewal scenario that needs to hold the lock continuously, a value of at least 3s is recommended.
func WithPrefix ¶
WithPrefix sets the key prefix.
The final lock key is prefix + ":" + name; when the prefix is empty no concatenation happens.
Source Files