Make fast event-wait channels easier to poll

[Gary Dixon]

The Inter-Process Communication (IPC) facility provides 4 types of event channels for notifying a process of an external event: fast event-wait, (regular) event-wait, event-call and async event-call channel types. The caller of ipc_$create_event_channel selects one of these types when creating a new channel.

• An event-wait channel receives events that are recorded as having occurred. The process owning the channel is awakened if it called ipc_$block to wait for an event on that channel. Or the owning process can call ipc_$read_ev_chn to check if the channel has received an event. An event_wait_info structure is returned to the caller by both of these subroutines.

• A fast event-wait channel operates like a regular event-wait channel, but has no event record associated with each event. Instead there is one bit, the fast event bit which gets set to record that one or more events have been reported on that channel. Both ipc_$block and ipc_$read_ev_chn check and clear this bit when they report occurrence of the fast event-wait. It is one of 36 event bits stored in ipc_data_$fast_channel_events external static variable of the Event Channel Table (ECT).

The other two types are the event-call channel, and async event-call channel. Neither of these two types factor into this discussion.

For a fast event-wait channel, there should be some way to return a pointer to fast_event_bit. That would permit the owner of a channel to rapidly check if an event had been reported while his process had been blocked (preempted for quantum run-out, or waiting for a timer to expire, or perhaps calling ipc_$block directly to wait for other event-wait channels).

This would allow the owner to poll event status directly.

• If the owner found the fast_event_bit = "1"b, the bit could be cleared (set to "0"b) and the owner could then respond to the event (processing an pending inputs or outputs).

• If the owner found the fast_event_bit = "0"b, it would not necessarily mean the event had not received a wake-up. It might be that his process had not blocked in the past, so notification of the event might not have moved from the system-wide Interprocess Transmission Table (ITT) into the owner's Event Channel Table (ECT). To be sure no event had occurred, the owner could:

Call ipc_$read_ev_chn to have IPS call its internal copy_itt_messages which moves data from the ITT into the ECT, and also updates fast event channel bits in ipc_data_$fast_channel_events bit array. The flag returned by ipc_$read_ev_chn would tell the owner definitely whether his channel's fast_event_bit had received a wake-up.

Note that cost of checking and clearing the fast_event_bit is significantly less than the cost of calling ipc_$read_ev_chn. Depending upon the owner's non-polling activity, he might often find posting of that bit due to other blocking of his process; and thereby avoid the overhead of the ips_$read_ev_chn call.

Therefore, this ticket requests an enhancement to ips_$create_event_channel to return a pointer to the fast_event_bit associated with a new fast event-wait channel as one of its output values.

---

The input to ipc_$create_event_channel is a data structure.

dcl  1 ipc_create_arg_structure      aligned based (ipc_create_arg_structure_ptr),
       2 version                     char (8) unaligned    init(ipc_create_arg_structure_v1),
       2 channel_type                fixed bin,             /* See constants below. */
       2 pad1                        fixed bin,
       2 call_entry                  variable entry (ptr),  /* For event call channels -- who to call. */
       2 call_data_ptr               ptr,                   /* For event call channels -- something to tell them. */
       2 call_priority               fixed bin (17),        /* For event call channels -- who's first? */
       2 pad5                        fixed bin,

     ipc_create_arg_structure_ptr    ptr;

When creating either regular or fast event-wait channel, only version and channel_type elements are referenced. The other elements relate to event-call channel creation.

So my suggestion is to make use of the call_data_ptr element when creating a fast event-wait channel by having ipc_$create_event_channel make it point to the fast_event_bit associated with the newly-created channel.

This could be done by adding two structures designed to create event-wait channels.

dcl  1 ipc_create_wait_event         aligned automatic,
       2 version                     char (8) unaligned    init(ipc_create_arg_structure_v1),
       2 channel_type                fixed bin             init(WAIT_EVENT_CHANNEL_TYPE),
       2 pad1                        fixed bin,
       2 pad2                        variable entry (ptr),
       2 pad3                        ptr,
       2 pad4                        fixed bin,
       2 pad5                        fixed bin;


dcl  1 ipc_create_fast_event         aligned automatic,
       2 version                     char (8) unaligned    init(ipc_create_arg_structure_v1),
       2 channel_type                fixed bin             init(FAST_EVENT_CHANNEL_TYPE),
       2 pad1                        fixed bin,
       2 pad2                        variable entry (ptr),
       2 event_bit_ptr               ptr                   init(null()),
                                                            /* For fast event wait channels                */
                                                            /*  -- output ptr which locates fast_event_bit */
       2 pad4                        fixed bin,
       2 pad5                        fixed bin,

      fast_event_bit                 bit(1) unaligned based (ipc_create_fast_event.event_bit_ptr);

---

In the current ipc_create_arg.incl.pl1, the existing ipc_create_arg_structure is declared:

dcl  1 ipc_create_arg_structure      aligned based (ipc_create_arg_structure_ptr),
       2 version                     char (8) unaligned,    /* From above. */
       2 channel_type                fixed bin,             /* See constants below. */
       2 call_entry                  variable entry (ptr),  /* For event call channels -- who to call. */
       2 call_data_ptr               ptr,                   /* For event call channels -- something to tell them. */
       2 call_priority               fixed bin (17);        /* For event call channels -- who's first? */

The pad1 and pad5 elements are missing, but the gap between channel_type and call_entry still exists, because the entry data type must be aligned on an even-word boundary; and the pad5 word does exist because the entire structure is aligned on a double-word boundary and is an even number of words in length. Coding standards require that all space within a public structure be explicitly declared. So I have added the pad1 and pad5 elements to represent this hidden space in my proposal above.

[Gary Dixon]

MCR10167 will implement this accepted enhancement.