summaryrefslogtreecommitdiffstats
path: root/doc/user/timer.t
blob: 421fc4f0320ed79f3cae771b9c8e080647141a98 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@chapter Timer Manager

@cindex timers

@section Introduction

The timer manager provides support for timer
facilities.  The directives provided by the timer manager are:

@itemize @bullet
@item @code{@value{DIRPREFIX}timer_create} - Create a timer
@item @code{@value{DIRPREFIX}timer_ident} - Get ID of a timer
@item @code{@value{DIRPREFIX}timer_cancel} - Cancel a timer
@item @code{@value{DIRPREFIX}timer_delete} - Delete a timer
@item @code{@value{DIRPREFIX}timer_fire_after} - Fire timer after interval
@item @code{@value{DIRPREFIX}timer_fire_when} - Fire timer when specified
@item @code{@value{DIRPREFIX}timer_initiate_server} - Initiate server for task-based timers
@item @code{@value{DIRPREFIX}timer_server_fire_after} - Fire task-based timer after interval
@item @code{@value{DIRPREFIX}timer_server_fire_when} - Fire task-based timer when specified
@item @code{@value{DIRPREFIX}timer_reset} - Reset an interval timer
@end itemize


@section Background

@subsection Required Support

A clock tick is required to support the functionality provided by this manager.

@subsection Timers

A timer is an RTEMS object which allows the
application to schedule operations to occur at specific times in
the future.  User supplied timer service routines are invoked by
either the @code{@value{DIRPREFIX}clock_tick} directive or
a special Timer Server task when the timer fires.  Timer service
routines may perform any operations or directives which normally
would be performed by the application code which invoked the
@code{@value{DIRPREFIX}clock_tick} directive.

The timer can be used to implement watchdog routines
which only fire to denote that an application error has
occurred.  The timer is reset at specific points in the
application to insure that the watchdog does not fire.  Thus, if
the application does not reset the watchdog timer, then the
timer service routine will fire to indicate that the application
has failed to reach a reset point.  This use of a timer is
sometimes referred to as a "keep alive" or a "deadman" timer.

@subsection Timer Server

The Timer Server task is responsible for executing the timer
service routines associated with all task-based timers. 
This task executes at a priority higher than any RTEMS application
task and thus can be viewed logically as the lowest priority interrupt.

By providing a mechanism where timer service routines execute
in task rather than interrupt space, the application is 
allowed a bit more flexibility in what operations a timer
service routine can perform.  For example, the Timer Server
can be configured to have a floating point context in which case
it would be save to perform floating point operations
from a task-based timer.  Most of the time, executing floating
point instructions from an interrupt service routine
is not considered safe.

The Timer Server is designed to remain blocked until a 
task-based timer fires.  This reduces the execution overhead
of the Timer Server.

@subsection Timer Service Routines

The timer service routine should adhere to @value{LANGUAGE} calling
conventions and have a prototype similar to the following:

@ifset is-C
@findex rtems_timer_service_routine
@example
rtems_timer_service_routine user_routine(
  rtems_id   timer_id,
  void      *user_data
);
@end example
@end ifset

@ifset is-Ada
@example
procedure User_Routine(
  Timer_ID  : in     RTEMS.ID;
  User_Data : in     System.Address
);
@end example
@end ifset

Where the timer_id parameter is the RTEMS object ID
of the timer which is being fired and user_data is a pointer to
user-defined information which may be utilized by the timer
service routine.  The argument user_data may be NULL.

@section Operations

@subsection Creating a Timer

The @code{@value{DIRPREFIX}timer_create} directive creates a timer by
allocating a Timer Control Block (TMCB), assigning the timer a
user-specified name, and assigning it a timer ID.  Newly created
timers do not have a timer service routine associated with them
and are not active.

@subsection Obtaining Timer IDs

When a timer is created, RTEMS generates a unique
timer ID and assigns it to the created timer until it is
deleted.  The timer ID may be obtained by either of two methods.
First, as the result of an invocation of the
@code{@value{DIRPREFIX}timer_create}
directive, the timer ID is stored in a user provided location.
Second, the timer ID may be obtained later using the
@code{@value{DIRPREFIX}timer_ident} directive.  The timer ID
is used by other directives to manipulate this timer.

@subsection Initiating an Interval Timer

The @code{@value{DIRPREFIX}timer_fire_after}
and @code{@value{DIRPREFIX}timer_server_fire_after}
directives initiate a timer to fire a user provided
timer service routine after the specified
number of clock ticks have elapsed.  When the interval has
elapsed, the timer service routine will be invoked from the
@code{@value{DIRPREFIX}clock_tick} directive if it was initiated
by the @code{@value{DIRPREFIX}timer_fire_after} directive
and from the Timer Server task if initiated by the 
@code{@value{DIRPREFIX}timer_server_fire_after} directive.

@subsection Initiating a Time of Day Timer

The @code{@value{DIRPREFIX}timer_fire_when} 
and @code{@value{DIRPREFIX}timer_server_fire_when}
directive initiate a timer to
fire a user provided timer service routine when the specified
time of day has been reached.  When the interval has elapsed,
the timer service routine will be invoked from the
@code{@value{DIRPREFIX}clock_tick} directive
by the @code{@value{DIRPREFIX}timer_fire_when} directive
and from the Timer Server task if initiated by the 
@code{@value{DIRPREFIX}timer_server_fire_when} directive.

@subsection Canceling a Timer

The @code{@value{DIRPREFIX}timer_cancel} directive is used to halt the
specified timer.  Once canceled, the timer service routine will
not fire unless the timer is reinitiated.  The timer can be
reinitiated using the @code{@value{DIRPREFIX}timer_reset},
@code{@value{DIRPREFIX}timer_fire_after}, and
@code{@value{DIRPREFIX}timer_fire_when} directives.

@subsection Resetting a Timer

The @code{@value{DIRPREFIX}timer_reset} directive is used to restore an
interval timer initiated by a previous invocation of
@code{@value{DIRPREFIX}timer_fire_after} or
@code{@value{DIRPREFIX}timer_server_fire_after} to
its original interval length.  If the
timer has not been used or the last usage of this timer
was by the @code{@value{DIRPREFIX}timer_fire_when} 
or @code{@value{DIRPREFIX}timer_server_fire_when} 
directive, then an error is returned.  The timer service routine
is not changed or fired by this directive.

@subsection Initiating the Timer Server

The @code{@value{DIRPREFIX}timer_initiate_server} directive is used to 
allocate and start the execution of the Timer Server task.  The
application can specify both the stack size and attributes of the
Timer Server.  The Timer Server executes at a priority higher than
any application task and thus the user can expect to be preempted
as the result of executing the @code{@value{DIRPREFIX}timer_initiate_server}
directive.

@subsection Deleting a Timer

The @code{@value{DIRPREFIX}timer_delete} directive is used to delete a timer.
If the timer is running and has not expired, the timer is
automatically canceled.  The timer's control block is returned
to the TMCB free list when it is deleted.  A timer can be
deleted by a task other than the task which created the timer.
Any subsequent references to the timer's name and ID are invalid.

@section Directives

This section details the timer manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.

@c
@c
@c
@page
@subsection TIMER_CREATE - Create a timer

@cindex create a timer

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_create
@example
rtems_status_code rtems_timer_create(
  rtems_name  name,
  rtems_id   *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Create (
   Name   : in     RTEMS.Name;
   ID     :    out RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer created successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
@code{@value{RPREFIX}INVALID_NAME} - invalid timer name@*
@code{@value{RPREFIX}TOO_MANY} - too many timers created

@subheading DESCRIPTION:

This directive creates a timer.  The assigned timer
id is returned in id.  This id is used to access the timer with
other timer manager directives.  For control and maintenance of
the timer, RTEMS allocates a TMCB from the local TMCB free pool
and initializes it.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

@c
@c
@c
@page
@subsection TIMER_IDENT - Get ID of a timer

@cindex obtain the ID of a timer

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_ident
@example
rtems_status_code rtems_timer_ident(
  rtems_name  name,
  rtems_id   *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Ident (
   Name   : in     RTEMS.Name;
   ID     :    out RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer identified successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
@code{@value{RPREFIX}INVALID_NAME} - timer name not found

@subheading DESCRIPTION:

This directive obtains the timer id associated with
the timer name to be acquired.  If the timer name is not unique,
then the timer id will match one of the timers with that name.
However, this timer id is not guaranteed to correspond to the
desired timer.  The timer id is used to access this timer in
other timer related directives.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

@c
@c
@c
@page
@subsection TIMER_CANCEL - Cancel a timer

@cindex cancel a timer

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_cancel
@example
rtems_status_code rtems_timer_cancel(
  rtems_id id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Cancel (
   ID     : in     RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer canceled successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid timer id

@subheading DESCRIPTION:

This directive cancels the timer id.  This timer will
be reinitiated by the next invocation of @code{@value{DIRPREFIX}timer_reset},
@code{@value{DIRPREFIX}timer_fire_after}, or
@code{@value{DIRPREFIX}timer_fire_when} with this id.

@subheading NOTES:

This directive will not cause the running task to be preempted.

@c
@c
@c
@page
@subsection TIMER_DELETE - Delete a timer

@cindex delete a timer

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_delete
@example
rtems_status_code rtems_timer_delete(
  rtems_id id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Delete (
   ID     : in     RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer deleted successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid timer id

@subheading DESCRIPTION:

This directive deletes the timer specified by id.  If
the timer is running, it is automatically canceled.  The TMCB
for the deleted timer is reclaimed by RTEMS.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

A timer can be deleted by a task other than the task
which created the timer.

@c
@c
@c
@page
@subsection TIMER_FIRE_AFTER - Fire timer after interval

@cindex fire a timer after an interval

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_fire_after
@example
rtems_status_code rtems_timer_fire_after(
  rtems_id                           id,
  rtems_interval                     ticks,
  rtems_timer_service_routine_entry  routine,
  void                              *user_data
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Fire_After (
   ID        : in     RTEMS.ID;
   Ticks     : in     RTEMS.Interval;
   Routine   : in     RTEMS.Timer_Service_Routine;
   User_Data : in     RTEMS.Address;
   Result    :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid interval

@subheading DESCRIPTION:

This directive initiates the timer specified by id.
If the timer is running, it is automatically canceled before
being initiated.  The timer is scheduled to fire after an
interval ticks clock ticks has passed.  When the timer fires,
the timer service routine routine will be invoked with the
argument user_data.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

@c
@c
@c
@page
@subsection TIMER_FIRE_WHEN - Fire timer when specified

@cindex fire a timer at wall time

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_fire_when
@example
rtems_status_code rtems_timer_fire_when(
  rtems_id                           id,
  rtems_time_of_day                 *wall_time,
  rtems_timer_service_routine_entry  routine,
  void                              *user_data
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Fire_When (
   ID        : in     RTEMS.ID;
   Wall_Time : in     RTEMS.Time_Of_Day;
   Routine   : in     RTEMS.Timer_Service_Routine;
   User_Data : in     RTEMS.Address;
   Result    :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{wall_time} is NULL@*
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day

@subheading DESCRIPTION:

This directive initiates the timer specified by id.
If the timer is running, it is automatically canceled before
being initiated.  The timer is scheduled to fire at the time of
day specified by wall_time.  When the timer fires, the timer
service routine routine will be invoked with the argument
user_data.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

@c
@c
@c
@page
@subsection TIMER_INITIATE_SERVER - Initiate server for task-based timers

@cindex initiate the Timer Server

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_initiate_server
@example
rtems_status_code rtems_timer_initiate_server(
  unsigned32           stack_size,
  rtems_attribute      attribute_set
)
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Initiate_Server (
   Stack_Size    : in     RTEMS.Unsigned32;
   Attribute_Set : in     RTEMS.Attribute;
   Result        :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - Timer Server initiated successfully@*
@code{@value{RPREFIX}TOO_MANY} - too many tasks created

@subheading DESCRIPTION:

This directive initiates the Timer Server task.  This task
is responsible for executing all timers initiated via the
@code{@value{DIRPREFIX}timer_server_fire_after} or
@code{@value{DIRPREFIX}timer_server_fire_when} directives.

@subheading NOTES:

This directive could cause the calling task to be preempted.

The Timer Server task is created using the 
@code{@value{DIRPREFIX}task_create} service and must be accounted
for when configuring the system.

Even through this directive invokes the @code{@value{DIRPREFIX}task_create}
and @code{@value{DIRPREFIX}task_start} directives, it should only fail
due to resource allocation problems.

@c
@c
@c
@page
@subsection TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval

@cindex fire task-based a timer after an interval

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_server_fire_after
@example
rtems_status_code rtems_timer_server_fire_after(
  rtems_id                           id,
  rtems_interval                     ticks,
  rtems_timer_service_routine_entry  routine,
  void                              *user_data
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Fire_Server_After (
   ID        : in     RTEMS.ID;
   Ticks     : in     RTEMS.Interval;
   Routine   : in     RTEMS.Timer_Service_Routine;
   User_Data : in     RTEMS.Address;
   Result    :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
@code{@value{RPREFIX}INVALID_NUMBER} - invalid interval@*
@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated

@subheading DESCRIPTION:

This directive initiates the timer specified by id and specifies
that when it fires it will be executed by the Timer Server.

If the timer is running, it is automatically canceled before
being initiated.  The timer is scheduled to fire after an
interval ticks clock ticks has passed.  When the timer fires,
the timer service routine routine will be invoked with the
argument user_data.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

@c
@c
@c
@page
@subsection TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified

@cindex fire a task-based timer at wall time

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_server_fire_when
@example
rtems_status_code rtems_timer_server_fire_when(
  rtems_id                           id,
  rtems_time_of_day                 *wall_time,
  rtems_timer_service_routine_entry  routine,
  void                              *user_data
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Fire_Server_When (
   ID        : in     RTEMS.ID;
   Wall_Time : in     RTEMS.Time_Of_Day;
   Routine   : in     RTEMS.Timer_Service_Routine;
   User_Data : in     RTEMS.Address;
   Result    :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer initiated successfully@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{routine} is NULL@*
@code{@value{RPREFIX}INVALID_ADDRESS} - @code{wall_time} is NULL@*
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day@*
@code{@value{RPREFIX}INCORRECT_STATE} - Timer Server not initiated

@subheading DESCRIPTION:

This directive initiates the timer specified by id and specifies
that when it fires it will be executed by the Timer Server.

If the timer is running, it is automatically canceled before
being initiated.  The timer is scheduled to fire at the time of
day specified by wall_time.  When the timer fires, the timer
service routine routine will be invoked with the argument
user_data.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

@c
@c
@c
@page
@subsection TIMER_RESET - Reset an interval timer

@cindex reset a timer

@subheading CALLING SEQUENCE:

@ifset is-C
@findex rtems_timer_reset
@example
rtems_status_code rtems_timer_reset(
  rtems_id   id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Timer_Reset (
   ID     : in     RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{@value{RPREFIX}SUCCESSFUL} - timer reset successfully@*
@code{@value{RPREFIX}INVALID_ID} - invalid timer id@*
@code{@value{RPREFIX}NOT_DEFINED} - attempted to reset a when or newly created timer

@subheading DESCRIPTION:

This directive resets the timer associated with id.
This timer must have been previously initiated with either the
@code{@value{DIRPREFIX}timer_fire_after} or
@code{@value{DIRPREFIX}timer_server_fire_after} 
directive.  If active the timer is canceled,
after which the timer is reinitiated using the same interval and
timer service routine which the original
@code{@value{DIRPREFIX}timer_fire_after}
@code{@value{DIRPREFIX}timer_server_fire_after}
directive used.

@subheading NOTES:

If the timer has not been used or the last usage of this timer
was by a @code{@value{DIRPREFIX}timer_fire_when} or
@code{@value{DIRPREFIX}timer_server_fire_when}
directive, then the @code{@value{RPREFIX}NOT_DEFINED} error is
returned. 

Restarting a cancelled after timer results in the timer being 
reinitiated with its previous timer service routine and interval.

This directive will not cause the running task to be preempted.