Skip to main content

%SYSTEM.Event

Class %SYSTEM.Event Extends Help [ Not ProcedureBlock, System = 4 ]

The %SYSTEM.Event class provides an interface to the Event API.

Event Queueing in InterSystems IRIS

Overview

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)

A process can wait on any Named Resource or on its own Process Id, but not on some other process' process id. A process can issue a wakeup to any resource.

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).

For both types of resources, when a wakeup call is issued, it either: a) wakes one of the processes that was waiting on that resource, or, if no-one was waiting, it b) queues up a wakeup for that resource so that as soon as a process tries to wait on that resource it immediately gets awakened. Thus wakeups can be queued prior to someone actually going to sleep on the resource.

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.

Methods​

Create​

ClassMethod Create(ResourceName As %String) As %Integer [ CodeMode = expression ]

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.

Wait​

ClassMethod Wait(ResourceName As %String = NULL, timeout As %Decimal = -1) As %Integer [ CodeMode = expression ]

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., it can be integer or decimal values, it can be down to 100th seconds). 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

WaitMsg​

ClassMethod WaitMsg(ResourceName As %String = NULL, timeout As %Numeric = -1) As %List [ CodeMode = expression ]

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).

Signal​

ClassMethod Signal(ResourceName As %String, Message As %String) As %Integer [ CodeMode = expression ]

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.

Clear​

ClassMethod Clear(ResourceName As %String) As %Integer [ CodeMode = expression ]

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​

ClassMethod Count(ResourceName As %String) As %Integer [ CodeMode = expression ]

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

Delete​

ClassMethod Delete(ResourceName As %String) As %Integer [ CodeMode = expression ]

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.

Defined​

ClassMethod Defined(ResourceName As %String) As %Integer [ CodeMode = expression ]

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.

List​

ClassMethod List() As %List [ CodeMode = expression ]

Returns a list of all the Named Resources currently defined.

ListClose​

ClassMethod ListClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = ListExecute ]

ListExecute​

ClassMethod ListExecute(ByRef qHandle As %Binary) As %Status [ Internal ]

ListFetch​

ClassMethod ListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = ListExecute ]