Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

SYS.DLM

Interface to operating system supplied Distributed Lock Manager for clustered systems

This class is used internally by Caché. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this class.

This is for use on clustered systems where Cache' supports forming a Cache' cluster. The operating system on these systems provides a Distributed Lock Manager, DLM, which implements cluster wide resources. Limited access to manipulating DLM resources is provided here. There is support for acquiring, converting and releasing resources. There is no support for asynchronous lock operations, utilizing the lock value block to carry information or for specifying a blocking notification routine.

When Cache' is installed on a cluster, Cache' can be configured to form a Cache' cluster where a single database can be directly accessed by multiple copies of Cache' simultaneously. Multiple copies of Cache' can be installed on the hardware and multiple distinct Cache' clusters can be created. The locks taken out by this class can be either Cache' cluster wide or Hardware cluster wide. The former, Cache' cluster wide locks, only conflict with lock requests from other Cache' systems that are a member of the same Cache' cluster. Hardware cluster wide locks conflict across all instances of Cache' running in the entire cluster. The namespace for these two types of locks is different so a resouce locked across a Cache' cluster will not conflict with a resource of the same name locked across the hardware cluster. GlobalLockFlag controls what kind of lock is taken out. The default is FALSE which means Cache' cluster wide.

The three methods in this class that are used to manipulate locks are acquire(), convert() and release(). A lock is aquired and released once (although once released, a lock can be acquired again) and the mode of an existing lock is changed with the convert method. The modes for the lock mode argument to acquire() and convert() are defined in %SYSTEM.DLMLockModes.

Locks taken out by this class only exist as long as the object is instantiated. If the object is closed either explicitly, because it goes out of scope, or because the process exits Cache', the lock is automatically released. If you need locks to have a lifetime beyond the scope of a process you need to create a agent which can jobbed off and handles requests (made via some communication channel) on behalf of the Cache' processes.

The Timeout property controls how long to wait for a lock which cannot be granted at the moment. The default value is 0 which means that lock requests complete immediately, either successfully or unsuccessfully. Locks that time out return a status of -1 to differentiate timeout failures from other errors acquiring the lock. A negative timeout value means that the lock request never times out and a positive value is the number of seconds to wait for the lock before giving up. If you specify a positive timeout but do not disable DeadlockDetection the lock may complete with a failure code before the timeout is reached due to a deadlock scan. When deadlock scan is enabled, the operating system scans pending requests for locks that cannot complete because a conflicting lock is held by the same process or by another process which is waiting for a lock this process holds. Typically the deadlock scan interval is on the order of 5 seconds although this can be tuned with operating system parameters. Deadlock detection can be disabled by setting DeadlockDetection to FALSE. However this should be done with care if untimed lock requests are used as while a CTRL/C, RESJOB, etc, will interrupt a waiting lock request, there is no way to programatically give up on a lock request once it has been issued.

[The following section subject to change to align the return values with the "standard" return value system for objects]
The methods in this class return 1 for success, 0 for failure and -1 for timeout. When 0 is returned ErrorCode contains either the operating system error code or 0 if the error was detected by Cache' before issuing the lock request.

Property Inventory

Method Inventory

Properties

property CurrentMode as DLMLockModes [ InitialExpression = "NOLOCK" , ReadOnly ];
Read only property containing the mode of the lock currently held on this resource. NOLOCK means the resource is not currently locked.
Property methods: CurrentModeDisplayToLogical(), CurrentModeIsValid(), CurrentModeLogicalToDisplay(), CurrentModeLogicalToOdbc(), CurrentModeNormalize()
property DeadlockDetection as %Boolean [ InitialExpression = 1 ];
Set to FALSE to disable the operating system deadlock detection scan for subsequent locks requests. This is TRUE (enabled) by default.
Property methods: DeadlockDetectionDisplayToLogical(), DeadlockDetectionGet(), DeadlockDetectionIsValid(), DeadlockDetectionLogicalToDisplay(), DeadlockDetectionNormalize(), DeadlockDetectionSet()
property ErrorCode as %Integer [ InitialExpression = 0 , ReadOnly ];
When a lock operation fails, other than due to a timeout, the failure code returned from the operating system lock operation is stored here. This is zeroed after a lock operation which succeeds or failes due to a timeout. This can also be zeroed when an error is returned if the error was detected by Cache' before passing the lock request to the operating system. This is a read-only property.
Property methods: ErrorCodeDisplayToLogical(), ErrorCodeGet(), ErrorCodeIsValid(), ErrorCodeLogicalToDisplay(), ErrorCodeNormalize()
property GlobalLockFlag as %Boolean [ InitialExpression = 0 ];
Normally locks acquired have a scope that covers only the instances of Cache that have joined the same cluster. When this is set to TRUE the locks have a scope that cover the entire "o/s" cluster. Locks taken out with GlobalLockFlag=FALSE do not conflict (eg. are different locks) than those take out without GlobalLockFlag=TRUE.
Property methods: GlobalLockFlagDisplayToLogical(), GlobalLockFlagGet(), GlobalLockFlagIsValid(), GlobalLockFlagLogicalToDisplay(), GlobalLockFlagNormalize(), GlobalLockFlagSet()
property ResourceName as %String [ ReadOnly ];
Read only resource name for this lock object. Limited to a maximum length of 16 bytes
Property methods: ResourceNameDisplayToLogical(), ResourceNameGet(), ResourceNameIsValid(), ResourceNameLogicalToDisplay(), ResourceNameLogicalToOdbc(), ResourceNameNormalize()
property Timeout as %Integer [ InitialExpression = 0 ];
Timeout in seconds for lock operations. Set to -1 means no timeout. Set to 0 means lock operations complete immediatly.
Property methods: TimeoutDisplayToLogical(), TimeoutGet(), TimeoutIsValid(), TimeoutLogicalToDisplay(), TimeoutNormalize(), TimeoutSet()
property lockid1 as %Integer [ InitialExpression = 0 , ReadOnly ];
part 1 of the internal lock id for a lock on a resource. This is read-only and is not generally interesting except for debugging using o/s supplied tools that let you examine lock's based on their id.
Property methods: lockid1DisplayToLogical(), lockid1Get(), lockid1IsValid(), lockid1LogicalToDisplay(), lockid1Normalize()
property lockid2 as %Integer [ InitialExpression = 0 , ReadOnly ];
part 2 of the internal lock id for a lock on a resource. This is read-only but is not generally interesting except for debugging using o/s supplied tools that let you examine lock's based on their id.
Property methods: lockid2DisplayToLogical(), lockid2Get(), lockid2IsValid(), lockid2LogicalToDisplay(), lockid2Normalize()

Methods

method %OnClose() as %Status
Inherited description: This callback method is invoked by the %Close() method to provide notification that the current object is being closed.

The return value of this method is ignored.

method %OnNew(ResourceName As %String = "") as %Status
Inherited description: This callback method is invoked by the %New() method to provide notification that a new instance of an object is being created.

If this method returns an error then the object will not be created.

It is passed the arguments provided in the %New call. When customizing this method, override the arguments with whatever variables and types you expect to receive from %New(). For example, if you're going to call %New, passing 2 arguments, %OnNew's signature could be:

Method %OnNew(dob as %Date = "", name as %Name = "") as %Status If instead of returning a %Status code this returns an oref and this oref is a subclass of the current class then this oref will be the one returned to the caller of %New method.

method CurrentModeGet() as %String
CurrentMode is read-only. It is set when a lock is acquired, released or converted.
method acquire(LockMode As DLMLockModes) as %Integer
Set up the Timeout and GlobalLockFlag before calling this method. Call this method to acquire the lock in specified mode. Returns -1 if the lock times out, 0 if there is an error and 1 for success. After success the convert and release methods can be called. Locks are automatically released when the object is closed.

There are two types of failure: o/s returns failure and errors detected internaly before the o/s routine is called. ErrorCode is set to 0 if it is an internally detected error otherwise it is set to the status returned by the o/s for the lock request. Examples of internal errors are the lock resource is too long, the lock is already held, the system has not joined a Cache cluster but the GlobalScopeFlag is set to FALSE.
classmethod canCluster() as %Boolean
TRUE if system supports clustering. If this is false, the methods in this API always return failure.
method convert(LockMode As DLMLockModes) as %Integer
Set up the Timeout before calling this method. This method issues a conversion request to alter the mode a lock is held in. The lock must already have been aquired. Returns -1 if the lock times out, 0 if there is an error and 1 for success.

There are two types of failure: o/s returns failure and an error is detected internally before the lock request was issued. The ErrorCode is set to 0 if it is an internally detected error otherwise it is set to the status returned by the o/s for the lock request. Issuing a convert before acquiring a lock or specifying an invalid mode are examples of internal errors.
classmethod isMember() as %Boolean
TRUE if this instance of Cache has joined a Cache cluster. When this returns false locks can only be taken out Cluster Wide by setting GlobalLockFlag to TRUE. The default for GlobalLockFlag is FALSE.
method release() as %Integer
Release a lock that is currently held. After this the lock must be acquired before the conversion method can be called. Returns 0 if there is an error and 1 for success.

There are two types of failure: o/s returns failure and an error is detected internally before the lock request was issued. The ErrorCode is set to 0 if it is an internally detected error otherwise it is set to the status returned by the o/s for the lock request. Issuing a release on a lock / which is not held is an example of an internal error.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab