Understanding the Event Queue

Within a keyed list structure allocated in a coupling facility of CFLEVEL=3 or higher, the system creates an event queue and an event queue controls object associated with each user. The event queue is created when the list structure is allocated with keyed list entries and is deleted when the list structure is deallocated. When you are monitoring an event (such as the state change of a sublist), the system queues or withdraws an event monitor controls (EMC) object to or from your associated event queue. For example, an EMC can be queued to your event queue when:

An empty to nonempty state transition occurs for a monitored sublist.
You register monitoring interest in a sublist at a time that the sublist is nonempty.

An EMC can be withdrawn from your event queue when:

A nonempty to empty state transition occurs for a monitored sublist. In this case, the system returns the EMC to association with its sublist.

An EMC can be dequeued from your event queue when:

You specifically request that the EMCs be retrieved and dequeued from the event queue. The EMC remains associated with its sublist.

An EMC can be deleted from the list structure when:

You deregister monitoring interest in a sublist. In this case, the system discards the EMC.
You disconnect from the structure or your connection terminates. The system deletes all EMCs associated with the connector.

The list services function uses the event queue for notifying a user that a state transition has occurred in one or more sublists that the user is monitoring. When a user registers interest in monitoring a sublist, list services creates an event monitor controls object (EMC) that associates and identifies both the user and the particular sublist. When the sublist transitions to a nonempty state, (or if the user registers interest in a sublist that is already in the nonempty state), the EMC is queued to the user's event queue. When the sublist transitions to an empty state, the EMC is withdrawn from the user's event queue but continues to be associated with the user and the monitored sublist.

By monitoring his event queue for the presence or absence of EMCs, the user is able to monitor one or more sublists in the structure. Each EMC uniquely identifies the sublist for which a transition has occurred.