$LOCK
| x | = a lock identifier (1 to 0xFFFF) |
| timeout | = a delay measured in ms |
| s | = a result code indicating if the lock was successful |
This is an experimental implementation for KCML 6.60 which is subject to change or even withdrawal
This statement allows access to operating system binary semaphores from a KCML program. To be compatible with the Unix convention for semaphore naming and to guarantee uniqueness on Unix systems the semaphores are identified by a 16 bit integer chosen by the programmer. In this implementation there is no attempt to abstract these identifiers.
The owner of the resource to be protected should pick an unused identifier, create the semaphore with CREATE $LOCK and publish the identifier to other potential users of the resource. It will then be available to all other processes on that application server. When the resource is no longer required the semaphore can be dropped with REMOVE $LOCK.
A process wishing to have exclusive access to the resource can attempt to lock it with a call to the $LOCK function with an optional timeout expressed in milliseconds. If the resource is in use by another process the call will block until the timeout expires. If there was no timeout given then the delay will be infinite. The return value of the $LOCK function will indicate if the request was successful or if it failed.
| result | Meaning |
|---|---|
| 1 | Lock was successful |
| 0 | Lock was unsuccessful and timed out |
| -1 | Lock failed due to operating system error or signal |
To release control of a resource the program should execute $UNLOCK. This will unblock another process which was blocked on a $LOCK waiting for the resource. If there was more than one such process blocked then it is an implementation choice as to which process is chosen. If the identifier is 0 then all semaphores held by the process are released.
CTRL-BREAK, $ALERT and $ALARM have no effect on a blocked $LOCK function, however it will be interrupted by RESET. Accessing a semaphore that does not exist will throw an X79 error. $LOCK of a semaphore which is already locked by a process will have no effect.
CLEAR and $END will unlock and destroy any semaphores created by the process and unlock any created elsewhere that were locked by the process.
It may be necessary to tune the kernel parameters for semaphores on some Unix implementations which support only a small number of semaphores or semaphore undo structures per process. Generally this is the SEMMNU macro which will need to bigger than the maximum number of processes that might be blocked on a semaphore.
Compatibility
This was introduced in KCML 6.60 as an experiment.
See also: