IRIS for UNIX 2019.2
Interface to operating system supplied Distributed Lock Manager for clustered systems
This class is used internally by InterSystems IRIS. 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 InterSystems IRIS supports forming a InterSystems IRIS 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 InterSystems IRIS is installed on a cluster, InterSystems IRIS can be configured to form a InterSystems IRIS cluster where a single database can be directly accessed by multiple copies of InterSystems IRIS simultaneously. Multiple copies of InterSystems IRIS can be installed on the hardware and multiple distinct InterSystems IRIS clusters can be created. The locks taken out by this class can be either InterSystems IRIS cluster wide or Hardware cluster wide. The former, InterSystems IRIS cluster wide locks, only conflict with lock requests from other InterSystems IRIS instances that are a member of the same InterSystems IRIS cluster. Hardware cluster wide locks conflict across all instances of InterSystems IRIS running in the entire cluster. The namespace for these two types of locks is different so a resouce locked across a InterSystems IRIS cluster will not conflict with a resource of the same name locked across the hardware cluster.
The three methods in this class that are used to manipulate locks are
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 InterSystems IRIS, 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 processes.
[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
Read only property containing the mode of the lock currently held on this resource. NOLOCK means the resource is not currently locked.
Set to FALSE to disable the operating system deadlock detection scan for subsequent locks requests. This is TRUE (enabled) by default.
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 before passing the lock request to the operating system. This is a read-only property.
Normally locks acquired have a scope that covers only the instances of InterSystems IRIS 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.
Read only resource name for this lock object. Limited to a maximum length of 16 bytes
Timeout in seconds for lock operations. Set to -1 means no timeout. Set to 0 means lock operations complete immediatly.
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.
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.
This callback method is invoked by the
%Closemethod to provide notification that the current object is being closed.
The return value of this method is ignored.
This callback method is invoked by the
%Newmethod 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.
CurrentMode is read-only. It is set when a lock is acquired, released or converted.
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 cluster but the GlobalScopeFlag is set to FALSE.
TRUE if system supports clustering. If this is false, the methods in this API always return failure.
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.
TRUE if this instance of InterSystems IRIS has joined a cluster. When this returns false locks can only be taken out Cluster Wide by setting GlobalLockFlag to TRUE. The default for GlobalLockFlag is FALSE.
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.