%SYSTEM.Event
class %SYSTEM.Event extends %SYSTEM.Help
The %SYSTEM.Event class provides an interface to the Cache Event API.Events Final
This feature allows processes to go to sleep waiting for a wakeup event for some resource. That "resource" can either be a "Named Resource" which can be used to queue multiple processes - one of which will be awakened for each wakeup event - or a Process ID Resource.
There are 2 types of resources on which processes can be queued for events:
- Named resources (which may be either a name or a global reference and are explicitly created and deleted), and
- Process ids (one of which implicitly exists for each process)
There are fundamentally 4 operations on resources:
- Create a resource (Named Resources only),
- Wait on a resource,
- Issue a Wakeup event for that resource, and
- Delete the resource (Named Resources only).
There is a one-to-one correspondence between wakeup events and process wakeups. E.g. if 5 processes are waiting for a Named Resource and 3 wakeup events occur for that resource, 3 of the processes will be issued wakeups. Similarly, if only one process ever waits on a particular resource and while the process is working on the result of one wakeup event 3 other wakeup events are queued for it, the next 3 calls by that process to the wait function for that resource will result in the process immediately continuing.
When multiple processes are waiting on a Named Resource there is no guarantee as to which one will be awakened next. (Note only one process can wait on a given Process ID since only the process with that PID can wait on it.)
If a wait is issued for a resource that doesn't exist, it is an error.
If a wakeup is issued for a resource that doesn't exist or for a non-existent PID, a 0 is returned to the caller.
There is no networking support for these functions - processes can only wait on and awaken resources on the same system.
Named Resources
A "Named Resource" gets "created" by a system call and thereafter one or more processes can wait on that resource for "wakeup" events for that resource.
Once a Named Resource is created, it continues in existence until either it is explicitly deleted or the system is shutdown. Thus these resources survive process termination.
A "Named Resource" is a string representation of a valid identifier. The syntax of the identifier is identical to the lock command.
Process ID Resources
"Process ID Resources" are system-wide values corresponding to process identifiers (value of $J) for cache processes. They are automatically created when a process is created and automatically deleted when a process exits. A process may wait only on its own process identifier.
In the Methods below, ResourceName must be in $name format, or else a FUNCTION error is returned.
Method Inventory
Methods
Clear wakeup events.
Sets the number of queued wakeup events for a resource to 0.
Resource may be either a Named Resource or a Process ID Resource. If it is a Process ID Resource, the target process' PID is used (i.e. $J of the process to be awakened - which must be an integer value.)
A return value of 1 implies success.
If the resource does not exist, a Named Resource gives an
error (ERUNDEF), while a Process ID Resource gives a return code of 0
Count wakeup events.
Resource may be either a Named Resource or a Process ID Resource. If it is a Process ID Resource, the target process' PID is used (i.e. $J of the process to be awakened - which must be an integer value.)
The return value is the current count of queued wakeup events for that resource.
If the resource does not exist, a Named Resource gives an
error (ERUNDEF), while a Process ID Resource gives a return code of -1
Create a Named Resource.
ResourceName is a Named Resource, e.g. 'Lab', '^Queue("main")', etc.
Returns 0 if there was already a Named Resource by that name (in which
case this function is ignored), else creates it and returns 1.
Test if a Named Resource has been created.
ResourceName is a Named Resource, e.g. 'Lab', '^Queue("main")', etc.
Returns 1 if there is a Named Resource by that name, else returns 0.
Delete a Named Resource.
The Named Resource is deleted and a value of 1 is returned, otherwise 0 is returned.
Any processes that were waiting on the resource when it was deleted
are awakened with a return code of -1.
Returns a list of all the Named Resources currently defined.
Wakeup a process waiting for a resource.
Enqueues a wakeup event for a resource. Resource may be either a Named Resource or a Process ID Resource. If it is a Process ID Resource, the target process' PID is used (i.e. $J of the process to be awakened - which must be an integer value.)
A return value of 1 implies success.
If the resource does not exist, a Named Resource gives an error (ERUNDEF), while a Process ID Resource gives a return code of 0
An optional message may be sent with the signal, and received via WaitMsg.
If the first process to receive the signal uses Wait(), the message is discarded.
Wait on a resource.
Resource, if present, is the name of a Named Resource or a null string. The default value for Resource is the null string. A null string for Resource means wait on my Process ID resource.
The timeout is identical to the lock command timeout, and affects the timeout in the same way (e.g., 0 is a timeout of 0 seconds, 2 is a timeout of 2 seconds, -1 is no timeout). The default value of timeout is -1.
An attempt to wait on a resource that doesn't exist is an error (ERUNDEF).
Return value:
- -1 implies a delete of the resource occurred while we were waiting
- 0 implies a timeout occurred
- 1 implies we were awakened due to a wakeup event
Wait on a resource and receive a message.
Identical to Event.Wait() except a string is returned along with the return code. See Signal().
Returns a $LIST item:
- Item #1 is the return code, identical to Wait().
- Item #2 is the string sent with the signal (a null string if no message was sent).
Queries
Returns a list of all the Named Resources currently defined.