1 01/16/85  ipc_
  2 
  3 The Multics system supports an interprocess communication facility.
  4 The basic purpose of the facility is to provide control communication
  5 (by means of stop and go signals) between processes.
  6 
  7 The ipc_ subroutine is the user's interface to the Multics
  8 interprocess communication facility where a process establishes event
  9 channels in the current protection ring and waits for an event on one
 10 or more channels.  For information on event channels, type "help
 11 event_channel.gi".
 12 
 13 
 14 Entry points in ipc_:
 15    (List is generated by the help command)
 16 
 17 
 18 :Entry:  block:  10/22/82 ipc_$block
 19 
 20 
 21 Function:  This entry point blocks the user's process until one or more
 22 of a specified list of events has occurred.
 23 
 24 
 25 Syntax:
 26 declare ipc_$block entry (ptr, ptr, fixed bin(35));
 27 call ipc_$block (event_wait_list_ptr, event_wait_info_ptr, code);
 28 
 29 
 30 Arguments:
 31 event_wait_list_ptr
 32    is a pointer to the event_wait_list structure that specifies the
 33    channels on which events are being awaited.  (Input) This structure
 34    is declared in event_wait_list.incl.pl1. Frequently ipc_$block is
 35    called with only one channel in the wait list.  In this case, the
 36    event_wait_channel structure can be used (declared in
 37    event_wait_channel.incl.pl1).
 38 event_wait_info_ptr
 39    is a pointer to the event_wait_info structure into which the
 40    ipc_$block entry point can put information about the event that
 41    caused it to return (i.e., that awakened the process).  This
 42    structure is declared in event_wait_info.incl.pl1.  (Input)
 43 code
 44    is a standard status code.  (Output)
 45 
 46 
 47 :Entry:  create_ev_chn:  10/22/82 ipc_$create_ev_chn
 48 
 49 
 50 Function:  This entry point creates an event-wait channel in the
 51 current ring.
 52 
 53 
 54 Syntax:
 55 declare ipc_$create_ev_chn entry (fixed bin(71), fixed bin(35));
 56 call ipc_$create_ev_chn (channel_id, code);
 57 
 58 
 59 Arguments:
 60 channel_id
 61    is the identifier of the event channel.  (Input)
 62 code
 63    is a standard status code.  (Output)
 64 
 65 
 66 :Entry:  cutoff:  01/16/85 ipc_$cutoff
 67 
 68 
 69 Function:  This entry point inhibits the reading of events on a
 70 specified event channel.  Any pending events are not affected.  More
 71 can be received, but do not cause the process to wake up.
 72 
 73 
 74 Syntax:
 75 declare ipc_$cutoff entry (fixed bin(71), fixed bin(35));
 76 call ipc_$cutoff (channel_id, code);
 77 
 78 
 79 Arguments:
 80 channel_id
 81    is the identifier of the event channel.  (Output)
 82 code
 83    is a standard status code.  (Output)
 84 
 85 
 86 :Entry:  decl_event_call_chn:  10/22/82 ipc_$decl_event_call_chn
 87 
 88 
 89 Function:  This entry point changes an event-wait channel into an
 90 event-call channel.
 91 
 92 
 93 Syntax:
 94 declare ipc_$decl_event_call_chn entry (fixed bin(71), entry, ptr,
 95      fixed bin, fixed bin(35));
 96 call ipc_$decl_event_call_chn (channel_id, call_chn_procedure,
 97      data_ptr, priority, code);
 98 
 99 
100 Arguments:
101 channel_id
102    is the identifier of the event channel.  (Input)
103 call_chn_procedure
104    is the procedure entry point invoked when an event occurs on the
105    specified channel.  (Input)  The procedure is called with one
106    argument, a pointer to the event_call_info structure which is
107    declared in event_call_info.incl.pl1.  Type "help event_channel.gi"
108    for details.
109 data_ptr
110    is a pointer to a region where data to be passed to and interpreted
111    by that procedure entry point is placed.  (Input)
112 
113 
114 priority
115    is a number indicating the priority of this event-call channel as
116    compared to other event-call channels declared by this process for
117    this ring.  If, upon interrogating all the appropriate event-call
118    channels, more than one is found to have received an event, the
119    lowest-numbered priority is honored first, and so on.  (Input)
120 code
121    is a standard status code.  (Output)
122 
123 
124 :Entry:  decl_ev_wait_chn:  10/22/82 ipc_$decl_ev_wait_chn
125 
126 
127 Function:  This entry point changes an event-call channel into an
128 event-wait channel.
129 
130 
131 Syntax:
132 declare ipc_$decl_ev_wait_chn entry (fixed bin(71), fixed bin(35));
133 call ipc_$decl_ev_wait_chn (channel_id, code);
134 
135 
136 Arguments:
137 channel_id
138    is the identifier of the event channel.  (Output)
139 code
140    is a standard status code.  (Output)
141 
142 
143 :Entry:  delete_ev_chn:  10/22/82 ipc_$delete_ev_chn
144 
145 
146 Function:  This entry point destroys an event channel previously
147 created by the process.
148 
149 
150 Syntax:
151 declare ipc_$delete_ev_chn entry (fixed bin(71), fixed bin(35));
152 call ipc_$delete_ev_chn (channel_id, code);
153 
154 
155 Arguments:
156 channel_id
157    is the identifier of the event channel.  (Output)
158 code
159    is a standard status code.  (Output)
160 
161 
162 :Entry:  drain_chn:  10/22/82 ipc_$drain_chn
163 
164 
165 Function:  This entry point resets an event channel so that any pending
166 events (i.e., events that have been received but not processed for that
167 channel) are removed.
168 
169 
170 Syntax:
171 declare ipc_$drain_chn entry (fixed bin(71), fixed bin(35));
172 call ipc_$drain_chn (channel_id, code);
173 
174 
175 Arguments:
176 channel_id
177    is the identifier of the event channel.  (Output)
178 code
179    is a standard status code.  (Output)
180 
181 
182 :Entry:  mask_ev_calls:  10/22/82 ipc_$mask_ev_calls
183 
184 
185 Function: This entry point causes the ipc_$block entry point to
186 completely ignore event-calls occurring in the user's ring at the time
187 of this call.  This call causes a mask counter to be incremented.
188 Event calls are masked if this counter is greater than zero.
189 
190 
191 Syntax:
192 declare ipc_$mask_ev_calls entry (fixed bin(35));
193 call ipc_$mask_ev_calls (code);
194 
195 
196 Arguments:
197 code
198    is a standard status code.  (Output)
199 
200 
201 :Entry:  read_ev_chn:  10/22/82 ipc_$read_ev_chn
202 
203 
204 Function:  This entry point reads the information about an event on a
205 specified channel if the event has occurred.
206 
207 
208 Syntax:
209 declare ipc_$read_ev_chn entry (fixed bin(71), fixed bin, ptr,
210      fixed bin(35));
211 call ipc_$read_ev_chn (channel_id, ev_occurred, event_wait_info_ptr,
212      code);
213 
214 
215 Arguments:
216 channel_id
217    is the identifier of the event channel.  (Input)
218 ev_occurred
219    indicates whether an event occurred on the specified channel.
220    (Output)
221    0 no event occurred
222    1 an event occurred
223 event_wait_info_ptr
224    is a pointer to the event_wait_info structure into which the
225    ipc_$block entry point can put information about the event that
226    caused it to return (i.e., that awakened the process).  This
227    structure is declared in event_wait_info.incl.pl1.  (Input)
228 code
229    is a standard status code.  (Output)
230 
231 
232 :Entry:  reconnect:  10/22/82 ipc_$reconnect
233 
234 
235 Function: This entry point enables the reading of events on a
236 specified event channel for which reading had previously been
237 inhibited (using the ipc_$cutoff entry point).  All pending signals,
238 whether received before or during the time reading was inhibited, are
239 henceforth available for reading.
240 
241 
242 Syntax:
243 declare ipc_$reconnect entry (fixed bin(71), fixed bin(35));
244 call ipc_$reconnect (channel_id, code);
245 
246 
247 Arguments:
248 channel_id
249    is the identifier of the event channel.  (Output)
250 code
251    is a standard status code.  (Output)
252 
253 
254 :Entry:  set_call_prior:  10/22/82 ipc_$set_call_prior
255 
256 
257 Function:  This entry point causes event-call channels to be given
258 priority over event-wait channels when several channels are being
259 interrogated; e.g., upon return from being blocked and waiting on any
260 of a list of channels.  Only event channels in the current ring are
261 affected.  By default, event-call channels have priority.
262 
263 
264 Syntax:
265 declare ipc_$set_call_prior entry (fixed bin(35));
266 call ipc_$set_call_prior (code);
267 
268 
269 Arguments:
270 code
271    is a standard status code.  (Output)
272 
273 
274 :Entry:  set_wait_prior:  10/22/82 ipc_$set_wait_prior
275 
276 
277 Function:  This entry point causes event-wait channels to be given
278 priority over event-call channels when several channels are being
279 interrogated; e.g., when a process returns from being blocked and is
280 waiting on any of a list of channels.  Only event channels in the
281 current ring are affected.
282 
283 
284 Syntax:
285 declare ipc_$set_wait_prior entry (fixed bin(35));
286 call ipc_$set_wait_prior (code);
287 
288 
289 Arguments:
290 code
291    is a standard status code.  (Output)
292 
293 
294 :Entry:  unmask_ev_calls:  10/22/82 ipc_$unmask_ev_calls
295 
296 
297 Function:  This entry point causes the event-call mask counter to be
298 decremented.  Event calls remain masked as long as the counter is
299 greater than zero.  To force event calls to become unmasked, call this
300 entry point repeatedly, until a nonzero code is returned.
301 
302 
303 Syntax:
304 declare ipc_$unmask_ev_calls entry (fixed bin(35));
305 call ipc_$unmask_ev_calls (code);
306 
307 
308 Arguments:
309 code
310    is a standard status code.  A nonzero code is returned if event
311    calls were not masked at the time of the call.  (Output)