Class %SYSTEM.Event

class %SYSTEM.Event extends Help

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

Events Final

Event Queueing in Cache 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.

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
		15	1

Summary

Methods
Clear	Count	Create	Defined	DefinedIP
Delete	Help	List	ListClose	ListExecute
ListFetch	ListIP	Signal	SignalIP	Wait
WaitMsg

Methods

• classmethod Clear(ResourceName As %String) as %Integer

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

• classmethod Count(ResourceName As %String) as %Integer

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

• classmethod Create(ResourceName As %String) as %Integer

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.

• classmethod Defined(ResourceName As %String) as %Integer

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.

• classmethod DefinedIP(ip As %String, port As %Integer, event As %String) as %Integer

Check if a Named Resource is defined on another machine.
The Named Resource is evaluated on the machine whose SuperServer IP address and port corresponds to the ip and port parameters.
Return codes:
1 - connection successful, Named Resource is defined
0 - connection failed
-1 - communication error
-2 - invalid event name
-3 - event undefined

• classmethod Delete(ResourceName As %String) as %Integer

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.

• classmethod List() as %List

Returns a list of all the Named Resources currently defined.

• classmethod ListIP(ip As %String, port As %Integer, ByRef events As %List) as %Integer

List Named Resources on another machine.
Returns a list of the Named Resources defined on the machine whose SuperServer IP address and port corresponds to the ip and port parameters.
Return codes:
1 - connection successful, operation successful
0 - connection failed
-1 - communication error

• classmethod Signal(ResourceName As %String, Message As %String) as %Integer

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.

• classmethod SignalIP(ip As %String, port As %Integer, event As %String) as %Integer

Wakeup a process waiting for a resource on another machine.
The Named Resource is signalled on the machine whose SuperServer IP address and port corresponds to the ip and port parameters.
Return codes:
1 - connection successful, operation successful
0 - connection failed
-1 - communication error
-2 - invalid event name
-3 - event undefined

• classmethod Wait(ResourceName As %String = NULL, timeout As %Integer = -1) as %Integer

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

• classmethod WaitMsg(ResourceName As %String = NULL, timeout As %Integer = -1) as %List

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

• query List()

Selects Event As %String

Returns a list of all the Named Resources currently defined.


[BASEXML] > [%SYSTEM] > [Event]		Private Storage