PgIpLock class

Implements manageable inter-process locking mechanism over existing PostgreSQL connection for a given LISTEN channel.

It uses periodic locks acquire retries and implements graceful shutdown using SIGINT, SIGTERM and SIGABRT OS signals, by which safely releases an acquired lock, which causes an event to other similar running instances on another processes (or on another hosts) to capture free lock.

By running inside Docker containers this would work flawlessly on implementation auto-scaling services, as docker destroys containers gracefully.

Currently, the only known issue could happen only if, for example, database or software (or hardware) in the middle will cause a silent disconnect. For some period of time, despite the fact that there are other live potential listeners some messages can go into void. This time period can be tuned by bypassing wanted acquireInterval argument. By the way, take into account that too short period and number of running services may cause huge flood of lock acquire requests to a database, so selecting the proper number should be a thoughtful trade-off between overall system load and reliability level.

Usually you do not need to instantiate this class directly - it will be done by a PgPubSub instances on their needs. Therefore, you may re-use this piece of code in some other implementations, so it is exported as is.

Signature:

export declare class PgIpLock implements AnyLock

Implements: AnyLock

Constructors

Constructor	Modifiers	Description
(constructor)(channel, options, uniqueKey)		Constructs a new instance of the `PgIpLock` class

Properties

Property	Modifiers	Type	Description
channel	`readonly`	string	Channel this lock guards. One lock row exists per channel, so this is what the competing processes contend over.
options	`readonly`	PgIpLockOptions	Connection, schema and retry settings for this lock.
schemaName	`readonly`	string	DB lock schema name getter
uniqueKey?	`readonly`	string \| undefined	(Optional) Optional content key making the lock a de-duplication marker for one specific payload rather than a listener election for the channel. Supplied by the execution-lock path; see `EXECUTION_LOCK`.

Methods

Method	Modifiers	Description
acquire()		Acquires a lock on the current channel. Returns true on success, false - otherwise
destroy()		Destroys this lock properly.
destroy()	`static`	Calls destroy() on all created instances at a time
dispose()		Frees all local resources held by this lock (acquire timer, client notification listener, global registry entry) without touching the database. Used directly when the underlying connection is already dead (e.g. on reconnect) and as a part of destroy().
hasInstances()	`static`	Returns true if at least one instance was created, false - otherwise
init()		Initializes inter-process locks storage in database and starts listening of lock release events, as well as initializes lock acquire retry timer.
isAcquired()		Returns current lock state, true if acquired, false - otherwise.
onAcquire(handler)		This would provide a late acquire handler which will be called once the lock is taken over by the retry timer, with the channel name bypassed to a given handler. Acquiring the lock is only ever half of the caller's job - the other half (issuing `LISTEN`, in the PgPubSub case) happens right after acquire() returns true. When the first attempt loses to another process, that caller is long gone by the time the timer wins the lock, so without this handler the second half never runs and the lock is held by a process that does nothing with it - forever, since a held lock keeps every other process away too.
onRelease(handler)		This would provide release handler which will be called once the lock is released and the channel name would be bypassed to a given handler
release()		Releases acquired lock on this channel. After lock is released, another running process or host would be able to acquire the lock.

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.