VX/LCKMGR: OpenVMS Lock Manager

In-memory data model

The daemon keeps one Lock Block (LKB) per outstanding request and one Resource Block (RSB) per named resource. Each RSB holds the three queues that drive arbitration: the grant queue, the conversion queue, and the wait queue. A Lock Holder record tracks each client session, and a sparse lock table indexed by a 24-bit slot plus an 8-bit generation counter turns a lock id back into its LKB. Named resources live in a ResourceDomain hierarchy so unrelated applications can share the daemon without colliding.

Request lifecycle

Every lock operation follows the same round trip between the client wrappers and the daemon:

A synchronous grant can be collapsed into the acknowledgement packet, so a lock that is immediately grantable returns without a separate AST round trip. A queued lock is granted later, when the resource frees up, by a reply message that the client's AST-dispatch thread turns into the caller's completion AST.

Compatibility matrix

A new request is granted immediately only if its mode is compatible with every lock already granted on the resource (and no conversion or wait is queued ahead of it). Rows are the mode of a currently granted lock; columns are the mode of the new request.

Grant and conversion rules

A request on a new resource is granted at once. On an existing resource it is granted only when the conversion and wait queues are empty and the mode is compatible with all granted locks; an NL request with the expedite option can jump the wait queue. Otherwise the request either returns SS$_NOTQUEUED when the no-queue option is set, or is appended to the wait queue. Conversions to a less restrictive mode are granted synchronously; conversions to a more restrictive mode are granted synchronously when compatible, and otherwise join the conversion queue while the lock stays granted at its current mode. When a lock is released or converted down, the conversion queue is re-evaluated up to the first incompatible entry, and the wait queue is evaluated once the conversion queue empties.

Example: enqueue, convert up, release

This is the common lock lifecycle for a shared resource. The example takes a system-wide lock on a banking account resource at NL mode, converts it up to EX to make an exclusive change, then releases it and writes the lock value block back. It checks both the routine return code and the lock status block after each step.

/* new NL-mode lock on a system-wide resource (async request, then wait) */
rc = sys$enq(efn, LCK$K_NLMODE, &lksb, LCK$M_SYSTEM,
             &resnam, 0, ast_granted, ctx, ast_blocked, PSL$C_USER, 0);
rc = sys$waitfr(efn);
if (!(rc & 1))            { request_error++; }
if (!(lksb.status & 1))   { grant_error++; }        /* not granted */

/* convert the same lock up to EX; LCK$M_CONVERT names the held lock id */
rc = sys$enqw(efn, LCK$K_EXMODE, &lksb,
              LCK$M_SYSTEM | LCK$M_VALBLK | LCK$M_CONVERT,
              0, 0, 0, 0, 0, PSL$C_USER, 0);

/* release; the value block is written back from lksb.valblk */
rc = sys$deq(lksb.lkid, &lksb.valblk, PSL$C_USER, 0);

The completion AST and the blocking AST are ordinary functions passed by address. The client-side AST-dispatch thread invokes them when the daemon publishes the matching reply on the process's AST channel, so the asynchronous behaviour of the VMS lock manager is preserved without the application changing how it waits.

Lock-state constants

These describe where a lock currently sits, and are returned for the state item code.

GETLKI item codes

The item codes select which field to return. Per-lock identity and state codes fall in the 256 to 264 range; namespace, resource, value block, and counter fields fall in the 512 to 524 range.

Return and completion status codes

These are the status values a lock request returns, in the routine return code or in the lock status block. They are distinct from the GETLKI item codes above.

Statistics

The statistics block reports service timestamps and a running set of counters: packets received, dispatched, and replied; blocking ASTs and grant ASTs fired; enqueue, dequeue, and query counts; how many requests took the grant, conversion, and wait paths; and outcome counters for no-queue rejections and deadlock-search cases. It also reports object counts (lock blocks, resource blocks, resource names, and active sessions) and per-arena memory use, with a memory-to-request ratio for capacity planning.

Audit log and replay

The daemon can record every lock request to an audit log and later replay it. Each record captures the operation, direction, timestamp, and the full request message, in a 32-bit-portable format so a recording made by one build can be read by another. Replay can be driven back through the daemon to reproduce a workload for tuning, or reported offline with the AuditHistory tool, which tallies enqueue, dequeue, and query volumes and prints an operations-per-second summary. Because replay reconstructs the request stream directly, bottlenecks can be isolated without re-running the original application.

Deliberate divergences

Lock modes

EX excludes all but NL; NL is compatible with every mode.

Client routines

Common request flags

Lock states

Operator commands

Scope

Single node, one lckmgr daemon per node, clients reached over a System V message queue. Up to 80,000 concurrent lock ids. No cluster mastering and no deadlock detection in the current build.