Documentation
¶
Overview ¶
Package unixlock provides inter-process mutual exclusion using Unix domain sockets. It creates a cooperative mutex at a specified file path, allowing processes to:
- Acquire and release locks.
- Communicate with the lock owner to request graceful shutdown.
- Query the owner's process ID (PID).
- Verify if the owner is an ancestor process.
The mutex supports non-blocking and blocking lock acquisition, context-aware cancellation, and status reporting between processes.
Index ¶
- Variables
- func Report(ctx context.Context, m *Mutex, status error) error
- func WaitForReport(ctx context.Context, m *Mutex) error
- func WithLock(ctx context.Context, m *Mutex) (context.Context, error)
- type Mutex
- func (m *Mutex) CheckAncestor(ctx context.Context) error
- func (m *Mutex) Close()
- func (m *Mutex) Lock(ctx context.Context, shutdown bool) (unlockf func(), status error)
- func (m *Mutex) Owner(ctx context.Context) (int, error)
- func (m *Mutex) SocketPath() string
- func (m *Mutex) TryLock(ctx context.Context) (unlockf func(), status error)
Constants ¶
This section is empty.
Variables ¶
var ErrShutdown = errors.New("shutdown")
ErrShutdown indicates the context was canceled due to a shutdown request.
var ErrUnlocked = errors.New("unlocked")
ErrUnlocked indicates the context was canceled because the lock was closed.
Functions ¶
func Report ¶
Report sends a status message to the parent process if it is the current lock owner. A nil status indicates success. Only one report can be sent per mutex; subsequent calls are no-ops. It returns an error if the report cannot be sent.
func WaitForReport ¶
WaitForReport blocks until a status report is received via the Unix domain socket or the context is canceled. It is used by parent processes to wait for initialization status from a child process.
func WithLock ¶
WithLock returns a context that is canceled when the input context is canceled, the mutex is unlocked (ErrUnlocked), or a shutdown request is received (ErrShutdown). It returns os.ErrInvalid if the mutex is not held by the current process. The mutex is not automatically unlocked when the context is canceled.
Types ¶
type Mutex ¶
type Mutex struct {
// contains filtered or unexported fields
}
func New ¶
New creates a cooperative mutual exclusion lock instance using a Unix domain socket at the specified file path. The mutex supports inter-process communication for shutdown requests, PID queries, and ancestor checks.
func (*Mutex) CheckAncestor ¶
CheckAncestor verifies if the lock owner is a parent or ancestor of the current process. It returns nil if the check passes, otherwise an error. The lock owner tracks PIDs of processes that pass this check to support deeply nested descendants.
func (*Mutex) Close ¶
func (m *Mutex) Close()
Close releases the lock if held by the current process and cancels all derived contexts with os.ErrClosed. It waits for all associated goroutines to terminate.
func (*Mutex) Lock ¶
Lock acquires the lock, waiting until it is available or the context expires. If shutdown is true, it sends a shutdown request to the owner before waiting. It returns an unlock function and nil on success, or an error on failure.
func (*Mutex) SocketPath ¶
SocketPath returns the monitor socket path.
Source Files