ipc_$create_event_channel and ipc_$run_event_calls should be documented

[Gary Dixon]

Two ipc_ entry points are not documented in ipc_.info. Their proposed documentation is summarized below.

Entry:  2025-02-07  ipc_$create_event_channel

Function:  This entry point creates a specified type of IPC event
channel.

Syntax:
declare ipc_$create_event_channel entry (ptr, fixed bin(71),
     fixed bin(35));
call ipc_$create_event_channel (create_structure_ptr, channel_id,
     code);

Arguments:
create_structure_ptr
   pointer to an ipc_create_arg_structure describing requirements for
   the new IPC channel. (Input)  For details, see the "Notes on the
   ipc_create_arg_structure" section below.
channel_id
   name for the new event channel. (Output)
code
   is a standard status code. (Output)

Notes on the ipc_create_arg_structure:
Input data for this subroutine is provided using the ipc_create_arg
structure described below.  A declaration for this structure and
related constants is provided in the ipc_create_arg.incl.pl1 segment.
Each element of the structure is described in the "List of
ipc_create_arg elements" section below.

dcl  1 ipc_create_arg_structure
                         aligned based (ipc_create_arg_structure_ptr),
     2 version           char (8) unaligned,
     2 channel_type      fixed bin,
     2 call_entry        variable entry (ptr),
     2 call_data_ptr     ptr,
     2 call_priority     fixed bin (17);

dcl  ipc_create_arg_structure_ptr    ptr;

dcl (ipc_create_arg_structure_v1     char (8)init ("ipcarg01"),
     FAST_EVENT_CHANNEL_TYPE         fixed bin  init (1),
     WAIT_EVENT_CHANNEL_TYPE         fixed bin  init (2),
     CALL_EVENT_CHANNEL_TYPE         fixed bin  init (3),
     ASYNC_CALL_EVENT_CHANNEL_TYPE   fixed bin  init (4),
     )                               int static options (constant);

List of ipc_create_arg_structure elements:
   The following items are elements of the ipc_create_arg_structure
   shown in the preceding section of this info segment.  The
   call_entry, call_data_ptr and call_priority must be given for an
   event call channel; but are ignored when creating an event wait
   channel.
version
   gives the version number of this structure. (Input)  Set it to
   the constant value ipc_create_arg_structure_v1 in the include
   segment.
channel_type
   gives the type of IPC event channel to be created. (Input)  See
   the "List of channel types" section below.

call_entry
   gives the entry point to call when an event call channel receives a
   wakeup. (Input)
call_data_ptr
   gives a pointer provided by the caller to any data needed by the
   call_entry. (Input)  Set this to null if no data additional is
   required.
call_priority
   gives the priority for this event call channel relative to other
   event call channels created by the calling process and ring. (Input)
   If a wakeup is pending for two or more call channels, the channel
   with the lowest priority number is called before other pending
   channels with higher numbers.

List of channel types:
   For details on the various types of event channels, type:
      help event_channel.gi

FAST_EVENT_CHANNEL_TYPE
   create a fast event wait channel.
WAIT_EVENT_CHANNEL_TYPE
   create a regular event wait channel.

CALL_EVENT_CHANNEL_TYPE
   create a regular event call channel.
ASYNC_CALL_EVENT_CHANNEL_TYPE
   create an asynchronous event call channel.

Notes on event wait channel types:
A regular event wait channel usually receives a wakeup to notify of
each channel event (one wakeup for each datum available through the
channel).  If all pending data is processed before blocking on that
wait channel, then drain all pending wakeups for that event wait
channel to indicate that all items were processed.  For more details,
type: help ipc_$drain_chn.

A fast event wait channel performs the same functions as a regular
event wait channel, but can record receipt of only one wakeup at a
time.  Therefore, a program requesting creation of a fast event wait
channel should process all data associated with that channel before
blocking again on the channel.  Calling ipc_$drain_chn is not required
for a fast event wait channel.

>udd>m>gd>w>hcsi>ipc_.info   (19 lines in entry point; 14 other entry points in info)

Entry:  2025-02-07  ipc_$run_event_calls

Function:  This entry point causes any pending event calls of the
specified type to run.  It makes one pass through the chains of pending
events instead of scanning from the beginning of the chain after each
event is processed (like ipc_$block).  The major reason for this entry
is for use by the wkp_ IPS signal handler whose contract is to run any
pending event calls in the process.

Syntax:
declare ipc_$run_event_calls (fixed bin(71), fixed bin(35));
call ipc_$run_event_calls (channel_id, code);

Arguments:
channel_id
   is the identifier of the event call channel whose pending event call
   wakeups are to be processed. (Input)
code
   is a standard status code. (Output)

[Eric Swenson]

​https://s3.amazonaws.com/eswenson-multics/mcrs/MCR10124.pdf

Fixed by MR12.9-1023.