D.14.1 Execution Time Timers
This subclause describes a language-defined package
that provides a facility for calling a handler when a task has used a
defined amount of CPU time.
The following language-defined
library package exists:
Nonblocking, Global => in out synchronized is
Timer (T : not null access constant
tagged limited private
access protected procedure
(TM : in out
Nonblocking => False;
Min_Handler_Ceiling : constant
Set_Handler (TM : in out
In_Time : in
Handler : in
Set_Handler (TM : in out
At_Time : in
Handler : in
Current_Handler (TM : Timer) return
Cancel_Handler (TM : in out
Cancelled : out
Time_Remaining (TM : Timer) return
Timer_Resource_Error : exception
... -- not specified by the language
The type Timer represents an execution-time event
for a single task and is capable of detecting execution-time overruns.
The access discriminant T identifies the task concerned. The type Timer
needs finalization (see 7.6
An object of type Timer is said to be set
if it is associated with a nonnull value of type Timer_Handler and cleared
otherwise. All Timer objects are initially cleared.
The type Timer_Handler identifies a protected procedure
to be executed by the implementation when the timer expires. Such a protected
procedure is called a handler
When a Timer object is created, or upon the first
call of a Set_Handler procedure with the timer as parameter, the resources
required to operate an execution-time timer based on the associated execution-time
clock are allocated and initialized. If this operation would exceed the
available resources, Timer_Resource_Error is raised.
The procedures Set_Handler associate the handler
Handler with the timer TM: if Handler is null
, the timer is cleared;
otherwise, it is set. The first procedure Set_Handler loads the timer
TM with an interval specified by the Time_Span parameter. In this mode,
the timer TM expires
when the execution time of the task identified
has increased by In_Time; if In_Time is less than
or equal to zero, the timer expires immediately. The second procedure
Set_Handler loads the timer TM with the absolute value specified by At_Time.
In this mode, the timer TM expires when the execution time of the task
identified by TM.T.all
reaches At_Time; if the value of At_Time
has already been reached when Set_Handler is called, the timer expires
A call of a procedure Set_Handler for a timer that
is already set replaces the handler and the (absolute or relative) execution
time; if Handler is not null, the timer remains set.
When a timer expires, the associated handler is executed,
passing the timer as parameter. The initial action of the execution of
the handler is to clear the event.
The function Current_Handler returns the handler
associated with the timer TM if that timer is set; otherwise, it returns
The procedure Cancel_Handler clears the timer if
it is set. Cancelled is assigned True if the timer was set prior to it
being cleared; otherwise, it is assigned False.
The function Time_Remaining returns the execution
time interval that remains until the timer TM would expire, if that timer
is set; otherwise, it returns Time_Span_Zero.
The constant Min_Handler_Ceiling is the minimum ceiling
priority required for a protected object with a handler to ensure that
no ceiling violation will occur when that handler is invoked.
As part of the finalization of an object of type
Timer, the timer is cleared.
For all the subprograms defined in this package,
Tasking_Error is raised if the task identified by TM.T.all has
terminated, and Program_Error is raised if the value of TM.T.all
An exception propagated from a handler invoked as
part of the expiration of a timer has no effect.
For a call of any of the subprograms
defined in this package, if the task identified by TM.T.all
longer exists, the execution of the program is erroneous.
For a given Timer object, the implementation shall
perform the operations declared in this package atomically with respect
to any of these operations on the same Timer object. The replacement
of a handler by a call of Set_Handler shall be performed atomically with
respect to the execution of the handler.
When an object of type Timer is finalized, the system
resources used by the timer shall be deallocated.
Implementations may limit the number of timers that
can be defined for each task. If this limit is exceeded, then Timer_Resource_Error
NOTE A Timer_Handler can be associated
with several Timer objects.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe