EventCreate — Create an Event Definition

Purpose

Use the EventCreate function to register the name of an event and specify how that event is to be managed.

Parameters

retcode

(output,INT,4) is a variable where the function stores the return code.

reascode

(output,INT,4) is a variable where the function stores the reason code.

event_name

(input,CHAR,event_name_length) is a variable for specifying the name of the event being defined.

event_name_length

(input,INT,4) is a variable for specifying the length of event_name.

event_flag

(input,INT,event_flag_size) is an array of 4-byte variables, each element of which contains information about how the event is to be managed. Only one option from each of the following sets may be specified. If no option from a particular set is specified, the default is taken.

• Scope of the event name

  vm_evn_process_scope

  Process (the default) — only this process can monitor this event and only this process can signal this event.

  vm_evn_session_scope

  Session — all processes in the session can both monitor and signal this event.

• Manner in which an event signal is delivered to multiple event monitors in a process

  vm_evn_broadcast_signals

  Broadcast (the default) — the signal is simultaneously delivered to all qualifying monitors.

  vm_evn_fifo_signals

  FIFO sequence — the signal is delivered to one qualifying monitor at a time, in the order the monitors were created.

  vm_evn_lifo_signals

  LIFO sequence — the signal is delivered to one qualifying monitor at a time, in the inverse order of their creation.

• The treatment of the signaler

  vm_evn_async_signals

  The signaling thread is allowed to continue executing (the default).

  vm_evn_sync_thread_signals

  The signaling thread is suspended until signal processing is complete. Signal processing in a process is considered complete when all qualifying monitors have completed processing of the signal or, if there are no qualifying monitors, the signal has been discarded as a result of being the oldest loose signal when the loose signal limit was exceeded.

  A monitor is considered to have completed processing a signal when that signal has become part of the current signal set of the monitor and that monitor has subsequently been reset. For FIFO and LIFO events, a bound signal may be explicitly discarded through EventDiscard or implicitly discarded if it is the oldest bound signal when the bound signal limit of the event list entry to which it is bound is exceeded. In either case, the processing of the discarded signal by that process is considered complete. If this is a session level event, all processes must complete processing before signal processing is considered complete.

  vm_evn_sync_process_signals

  All threads currently existing in the signaling process, with the exception of those threads running as the result of a monitor activated by this signal, are suspended to await the outcome of event processing. Threads running as the result of monitor activation may create additional threads that are not initially suspended. Upon monitor reset, however, the additional threads are treated as any other thread.

event_flag_size

(input,INT,4) is a variable for specifying the number of elements in the event_flag array.

loose_signal_limit

(input,INT,4) is a variable for specifying the number of event signals that may be retained if no eligible event monitor exists to which to bind the signal at the time the event is signaled. When the limit is exceeded, the oldest loose signal is discarded to make room for the newest arrival. A value of 0 indicates that no loose signals are to be retained. A value of -1 means that the loose signal list is allowed to grow without limit, subject to the availability of virtual storage. Any other negative value is considered an error.

signal_timeout_period

(input,INT,4) is a variable for specifying the maximum length of time, in microseconds, that a signaling thread should remain suspended awaiting the completion of processing of the signal. A value of 0 indicates that the signaling thread should wait indefinitely for the completion of signal processing. If the event is created such that the signaling thread is to continue processing, then this parameter is ignored.

Usage Notes

1. There is no restriction on the character composition of an event name. The length of an event name may not exceed 16MB. By convention, system event names consist of uppercase and lowercase alphabetic, numeric, and break characters, and have a maximum length of 24 bytes.
2. If the event name has session-level scope, the event may be signaled or monitored in any process in the session, and each signal is delivered to each eligible monitor in any process in the session. Such an event name must be unique among all event names known anywhere in the session.
3. If the event name has process-level scope, it may be signaled and monitored only in the process in which it was created, and each signal is delivered only to each eligible monitor in that process. Such an event name need only be unique within the creating process, however, and there may be multiple instances of an event definition with process-level scope in a session.
4. Signal propagation rules are applied on a process basis. When qualifying event handlers exist in several processes, the signal is always delivered to at least one event monitor in each process.

Return Codes and Reason Codes

Programming Language Bindings