A session lock is a server-managed resource that can be used to coordinate exclusive access to shared resources across sessions. For example, to ensure a single session has the right to update a topic; to ensure at most one session responds to an event; or to select a single session to perform a housekeeping task. Session locks support general collaborative locking schemes. The application architect is responsible for designing a suitable locking scheme and for ensuring each application component follows the scheme appropriately.
Session locks are identified by a lock name. Lock names are arbitrary and chosen at will to suit the application. Each lock is owned by at most one session. Locks are established on demand; there is no separate operation to create or destroy a lock.
A session lock is acquired using the Session.lock method.
If no other session owns the lock, the server will assign the lock to the
calling session immediately. Otherwise, the server will record that the
session is waiting to acquire the lock. A session can call
more than once for a given session lock – if the lock is acquired,
all calls will complete successfully with equal SessionLocks.
If a session closes, the session locks it owns are automatically
released. A session can also release a lock.
When a session lock is released and other sessions are waiting to acquire
the lock, the server will arbitrarily select one of the waiting sessions
and notify it that it has acquired the lock. All of the newly selected
lock calls will complete normally. Other
sessions will continue to wait.
The Session.lock method takes an optional scope parameter that provides the further option of automatically releasing the lock when the session loses its connection to the server.
This session lock API has inherent race conditions. Even if an application is coded correctly to protect a shared resource using session locks, there may be a period where two or more sessions concurrently access the resource. The races arise for several reasons including
Despite this imprecision, session locks provide a useful way to coordinate session actions.
Get the name of the lock
the name of the session lock
The scope of the lock.
The scope determines when the lock will be released automatically.
If a session makes multiple
requests for a lock
using different scopes, and the server assigns the lock to the session
fulfilling the requests, the lock will be given the weakest scope
UNLOCK_ON_CONNECTION_LOSS). Consequently, an individual request can
complete with a lock that has a different scope to that requested.
the lock scope
A value that identifies the acquisition of the lock with the given name. SessionLocks that are acquired later are guaranteed to have bigger sequence values, allowing the sequence number to be used as a fencing token.
a value that identifies the acquisition of this lock
Test whether the session lock is still owned.
true if the session lock is still owned by the session
Release a session lock, if owned.
a Promise that resolves when a response is received from the server.
On completion, this session will no longer own the named session lock. If Promise completes normally, a true value indicates this session previously owned the lock and a false value indicates it did not.
If the Promise resolves with an error, this session does not own the session lock.