1 06/20/87  timer_manager_
  2 
  3 The timer_manager_ subroutine allows many CPU usage timers and
  4 real-time timers to be used simultaneously by a process.  The caller
  5 can specify for each timer whether a wakeup is to be issued or a
  6 specified procedure is to be called when the timer goes off.  If a
  7 procedure is to be called, the calling procedure can specify a data
  8 pointer to pass to that procedure.
  9 
 10 Detailed information can be found in Multics Subroutines and I/O
 11 Modules (AG93).
 12 
 13 
 14 Entry points in timer_manager_:
 15    (List is generated by the help command)
 16 
 17 
 18 :Entry: alarm_call:  06/20/87 timer_manager_$alarm_call
 19 
 20 
 21 Function:  This entry point sets up a real-time timer that calls the
 22 routine specified when the timer goes off.
 23 
 24 
 25 Syntax:
 26 dcl timer_manager_$alarm_call entry (fixed bin(71), bit(2), entry,
 27      ptr);
 28 call timer_manager_$alarm_call (time, flags, routine, data_ptr);
 29 
 30 
 31 Arguments:
 32 time
 33    is the time at which the wakeup or call is desired.
 34 flags
 35    is a 2-bit string that determines how time is to be interpreted.
 36    timer_manager_constants.incl.pl1 defines the following named
 37    constants:
 38     ABSOLUTE_MICROSECONDS (="00"b)
 39     ABSOLUTE_SECONDS (="01"b)
 40     RELATIVE_MICROSECONDS (="10"b)
 41     RELATIVE_SECONDS (="11"b)
 42 routine
 43    is a procedure entry point that is called when the timer goes off.
 44 
 45 
 46 data_ptr
 47    is a pointer to a data structure which is to be associated with this
 48    particular timer.
 49 
 50 
 51 :Entry:  alarm_call_inhibit:  06/20/87 timer_manager_$alarm_call_inhibit
 52 
 53 
 54 Function:  This entry point sets up a real-time timer that calls the
 55 handler routine specified when the timer goes off.  The call is made
 56 with all interrupts inhibited (i.e., all interprocess signal (IPS) are
 57 masked off).  When the handler routine returns, interrupts are
 58 reenabled.  If the handler routine does not return, interrupts are not
 59 reenabled and the user process may malfunction.
 60 
 61 
 62 Syntax:
 63 dcl timer_manager_$alarm_call_inhibit entry (fixed bin(71), bit(2),
 64      entry, ptr);
 65 call timer_manager_$alarm_call_inhibit (time, flags, routine,
 66      data_ptr);
 67 
 68 
 69 Arguments:
 70 time
 71    is the time at which the wakeup or call is desired.
 72 flags
 73    is a 2-bit string that determines how time is to be interpreted.
 74    timer_manager_constants.incl.pl1 defines the following named
 75    constants:
 76     ABSOLUTE_MICROSECONDS (="00"b)
 77     ABSOLUTE_SECONDS (="01"b)
 78     RELATIVE_MICROSECONDS (="10"b)
 79     RELATIVE_SECONDS (="11"b)
 80 routine
 81    is a procedure entry point that is called when the timer goes off.
 82 
 83 
 84 data_ptr
 85    is a pointer to a data structure which is to be associated with this
 86    particular timer.
 87 
 88 
 89 :Entry:  alarm_wakeup:  06/20/87 timer_manager_$alarm_wakeup
 90 
 91 
 92 Function:  This entry point sets up a real-time timer that issues a
 93 wakeup on the event channel specified when the timer goes off.  The
 94 event message passed is the string "alarm___".  (See the ipc_
 95 subroutine for a discussion of event channels.)
 96 
 97 
 98 Syntax:
 99 declare timer_manager_$alarm_wakeup entry (fixed bin(71), bit(2),
100      fixed bin(71));
101 call timer_manager_$alarm_wakeup (time, flags, channel);
102 
103 
104 Arguments:
105 time
106    is the time at which the wakeup or call is desired.
107 flags
108    is a 2-bit string that determines how time is to be interpreted.
109    timer_manager_constants.incl.pl1 defines the following named
110    constants:
111     ABSOLUTE_MICROSECONDS (="00"b)
112     ABSOLUTE_SECONDS (="01"b)
113     RELATIVE_MICROSECONDS (="10"b)
114     RELATIVE_SECONDS (="11"b)
115 
116 
117 channel
118    is the name of the event channel over which a
119    wakeup is desired.  Two or more timers can be running
120    simultaneously, all of which may, if desired, issue a wakeup on the
121    same event channel.
122 
123 
124 :Entry:  cpu_call:  06/20/87 timer_manager_$cpu_call
125 
126 
127 Function:  This entry point sets up a CPU timer that calls the routine
128 specified when the timer goes off.
129 
130 
131 Syntax:
132 dcl timer_manager_$cpu_call entry (fixed bin(71), bit(2), entry, ptr);
133 call timer_manager_$cpu_call (time, flags, routine, data_ptr);
134 
135 
136 Arguments:
137 time
138    is the time at which the wakeup or call is desired.
139 flags
140    is a 2-bit string that determines how time is to be interpreted.
141    timer_manager_constants.incl.pl1 defines the following named
142    constants:
143     ABSOLUTE_MICROSECONDS (="00"b)
144     ABSOLUTE_SECONDS (="01"b)
145     RELATIVE_MICROSECONDS (="10"b)
146     RELATIVE_SECONDS (="11"b)
147 routine
148    is a procedure entry point that is called when the timer goes off.
149 
150 
151 data_ptr
152    is a pointer to a data structure which is to be associated with this
153    particular timer.
154 
155 
156 :Entry:  cpu_call_inhibit:  06/20/87 timer_manager_$cpu_call_inhibit
157 
158 
159 Function:  This entry point sets up a CPU timer that calls the handler
160 routine specified when the timer goes off.  The call is made with all
161 interrupts inhibited (i.e., all IPS are masked off).  When the handler
162 routine returns, interrupts are reenabled.  If the handler routine does
163 not return, interrupts are not reenabled and the user process may
164 malfunction.
165 
166 
167 Syntax:
168 dcl timer_manager_$cpu_call_inhibit entry (fixed bin(71), bit(2),
169      entry, ptr);
170 call timer_manager_$cpu_call_inhibit (time, flags, routine, data_ptr);
171 
172 
173 Arguments:
174 time
175    is the time at which the wakeup or call is desired.
176 flags
177    is a 2-bit string that determines how time is to be interpreted.
178    timer_manager_constants.incl.pl1 defines the following named
179    constants:
180     ABSOLUTE_MICROSECONDS (="00"b)
181     ABSOLUTE_SECONDS (="01"b)
182     RELATIVE_MICROSECONDS (="10"b)
183     RELATIVE_SECONDS (="11"b)
184 routine
185    is a procedure entry point that is called when the timer goes off.
186 
187 
188 data_ptr
189    is a pointer to a data structure which is to be associated with this
190    particular timer.
191 
192 
193 :Entry:  cpu_wakeup:  04/12/87 timer_manager_$cpu_wakeup
194 
195 
196 Function:  This entry point sets up a CPU timer that issues a wakeup on
197 the event channel specified when the timer goes off.  The event message
198 passed is the string "cpu_time".
199 
200 
201 Syntax:
202 declare timer_manager_$cpu_wakeup entry (fixed bin(71), bit(2),
203      fixed bin(71));
204 call timer_manager_$cpu_wakeup (time, flags, channel);
205 
206 
207 Arguments:
208 time
209    is the time at which the wakeup or call is desired.
210 flags
211    is a 2-bit string that determines how time is to be interpreted.
212    timer_manager_constants.incl.pl1 defines the following named
213    constants:
214     ABSOLUTE_MICROSECONDS (="00"b)
215     ABSOLUTE_SECONDS (="01"b)
216     RELATIVE_MICROSECONDS (="10"b)
217     RELATIVE_SECONDS (="11"b)
218 
219 
220 channel
221    is the name of the event channel over which a
222    wakeup is desired.  Two or more timers can be running
223    simultaneously, all of which may, if desired, issue a wakeup on the
224    same event channel.
225 
226 
227 :Entry:  reset_alarm_call:  04/12/87 timer_manager_$reset_alarm_call
228 
229 
230 Function:  This entry point turns off all real-time timers that call
231 the routine specified when they go off.
232 
233 
234 Syntax:
235 dcl timer_manager_$reset_alarm_call entry (entry);
236 call timer_manager_$reset_alarm_call (routine);
237    OR
238 dcl timer_manager_$reset_alarm_call entry (entry, ptr);
239 call timer_manager_$reset_alarm_call (routine, data_ptr);
240 
241 
242 Arguments:
243 routine
244    is a procedure entry point that is called when the timer goes off.
245 data_ptr
246    is a pointer to a data structure which is to be associated with this
247    particular timer.
248 
249 
250 Notes: If the data_ptr is provided, all real-time timers which are to
251 call the given routine with that value of data_ptr are cancelled.
252 Otherwise, all real-time timers which are to call that routine with
253 any value of data_ptr are cancelled.
254 
255 
256 :Entry:  reset_alarm_wakeup:  04/12/87 timer_manager_$reset_alarm_wakeup
257 
258 
259 Function:  This entry point turns off all real-time timers that issue a
260 wakeup on the event channel specified when they go off.
261 
262 
263 Syntax:
264 declare timer_manager_$reset_alarm_wakeup entry (fixed bin(71));
265 call timer_manager_$reset_alarm_wakeup (channel);
266 
267 
268 Arguments:
269 channel
270    is the name of the event channel over which a
271    wakeup is desired.  Two or more timers can be running
272    simultaneously, all of which may, if desired, issue a wakeup on the
273    same event channel.
274 
275 
276 :Entry:  reset_cpu_call:  04/12/87 timer_manager_$reset_cpu_call
277 
278 
279 Function:  This entry point turns off all CPU timers that call the
280 routine specified when they go off.
281 
282 
283 Syntax:
284 declare timer_manager_$reset_cpu_call entry (entry);
285 call timer_manager_$reset_cpu_call (routine);
286    OR
287 declare timer_manager_$reset_cpu_call entry (entry, ptr);
288 call timer_manager_$reset_cpu_call (routine, data_ptr);
289 
290 
291 Arguments:
292 routine
293    is a procedure entry point that is called when the timer goes off.
294 data_ptr
295    is a pointer to a data structure which is to be associated with this
296    particular timer.
297 
298 
299 Notes: If the data_ptr is provided, all CPU timers which are to call
300 the given routine with that value of data_ptr are cancelled.
301 Otherwise, all CPU timers which are to call the routine with any value
302 of data_ptr are cancelled.
303 
304 
305 :Entry:  reset_cpu_wakeup:  04/12/87 timer_manager_$reset_cpu_wakeup
306 
307 
308 Function:  This entry point turns off all CPU timers that issue a
309 wakeup on the event channel specified when they go off.
310 
311 
312 Syntax:
313 declare timer_manager_$reset_cpu_wakeup entry (fixed bin(71));
314 call timer_manager_$reset_cpu_wakeup (channel);
315 
316 
317 Arguments:
318 channel
319    is the name of the event channel over which a
320    wakeup is desired.  Two or more timers can be running
321    simultaneously, all of which may, if desired, issue a wakeup on the
322    same event channel.
323 
324 
325 :Entry:  sleep:  04/12/87 timer_manager_$sleep
326 
327 
328 Function:  This entry point causes the process to go blocked for a
329 period of real time.  Other timers that are active continue to be
330 processed whenever they go off; however, this routine does not return
331 until the real time has been passed.
332 
333 
334 Syntax:
335 dcl timer_manager_$sleep entry (fixed bin(71), bit(2));
336 call timer_manager_$sleep (time, flags);
337 
338 
339 Arguments:
340 time
341    is the time at which the wakeup or call is desired.
342 flags
343    is a 2-bit string that determines how time is to be interpreted.
344    timer_manager_constants.incl.pl1 defines the following named
345    constants:
346     ABSOLUTE_MICROSECONDS (="00"b)
347     ABSOLUTE_SECONDS (="01"b)
348     RELATIVE_MICROSECONDS (="10"b)
349     RELATIVE_SECONDS (="11"b)