Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [%SYSTEM] >  [Event]
Private  Storage   

class %SYSTEM.Event extends Help

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

Events Final

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:

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:

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
12 1


Summary

Methods
Clear Count Create Defined Delete
Help List Signal 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 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 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 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.
 



Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.