1 ------------------------------------------------------------------------------
3 -- GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- S Y S T E M . T A S K I N G --
9 -- Copyright (C) 1992-2002, Free Software Foundation, Inc. --
11 -- GNARL is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNARL; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNARL was developed by the GNARL team at Florida State University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
34 -- This package provides necessary type definitions for compiler interface.
36 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
37 -- Any changes to this interface may require corresponding compiler changes.
40 -- Used for: Exception_Id
42 with System
.Parameters
;
45 with System
.Task_Info
;
46 -- used for Task_Info_Type, Task_Image_Type
48 with System
.Soft_Links
;
51 with System
.Task_Primitives
;
52 -- used for Private_Data
54 with Unchecked_Conversion
;
56 package System
.Tasking
is
58 -- -------------------
59 -- -- Locking Rules --
60 -- -------------------
62 -- The following rules must be followed at all times, to prevent
63 -- deadlock and generally ensure correct operation of locking.
65 -- . Never lock a lock unless abort is deferred.
67 -- . Never undefer abort while holding a lock.
69 -- . Overlapping critical sections must be properly nested,
70 -- and locks must be released in LIFO order.
71 -- e.g., the following is not allowed:
81 -- Locks with lower (smaller) level number cannot be locked
82 -- while holding a lock with a higher level number. (The level
83 -- number is the number at the left.)
85 -- 1. System.Tasking.PO_Simple.Protection.L (any PO lock)
86 -- 2. System.Tasking.Initialization.Global_Task_Lock (in body)
87 -- 3. System.Task_Primitives.Operations.Single_RTS_Lock
88 -- 4. System.Tasking.Ada_Task_Control_Block.LL.L (any TCB lock)
90 -- Clearly, there can be no circular chain of hold-and-wait
91 -- relationships involving locks in different ordering levels.
93 -- We used to have Global_Task_Lock before Protection.L but this was
94 -- clearly wrong since there can be calls to "new" inside protected
95 -- operations. The new ordering prevents these failures.
97 -- Sometimes we need to hold two ATCB locks at the same time. To allow
98 -- us to order the locking, each ATCB is given a unique serial
99 -- number. If one needs to hold locks on several ATCBs at once,
100 -- the locks with lower serial numbers must be locked first.
102 -- We don't always need to check the serial numbers, since
103 -- the serial numbers are assigned sequentially, and so:
105 -- . The parent of a task always has a lower serial number.
106 -- . The activator of a task always has a lower serial number.
107 -- . The environment task has a lower serial number than any other task.
108 -- . If the activator of a task is different from the task's parent,
109 -- the parent always has a lower serial number than the activator.
111 ---------------------------------
112 -- Task_ID related definitions --
113 ---------------------------------
115 type Ada_Task_Control_Block
;
117 type Task_ID
is access all Ada_Task_Control_Block
;
119 Null_Task
: constant Task_ID
;
121 type Task_List
is array (Positive range <>) of Task_ID
;
123 function Self
return Task_ID
;
124 pragma Inline
(Self
);
125 -- This is the compiler interface version of this function. Do not call
126 -- from the run-time system.
128 function To_Task_Id
is new Unchecked_Conversion
(System
.Address
, Task_ID
);
129 function To_Address
is new Unchecked_Conversion
(Task_ID
, System
.Address
);
131 -----------------------
132 -- Enumeration types --
133 -----------------------
137 -- Task has been created but has not been activated.
138 -- It cannot be executing.
141 -- For all states from here down, the task has been activated.
142 -- For all states from here down, except for Terminated, the task
144 -- Activator = null iff it has not yet completed activating.
146 -- For all states from here down,
147 -- the task has been activated, and may be executing.
150 -- Task is not blocked for any reason known to Ada.
151 -- (It may be waiting for a mutex, though.)
152 -- It is conceptually "executing" in normal mode.
155 -- The task is terminated, in the sense of ARM 9.3 (5).
156 -- Any dependents that were waiting on terminate
157 -- alternatives have been awakened and have terminated themselves.
160 -- Task is waiting for created tasks to complete activation.
163 -- Task is waiting on an accept or selective wait statement.
166 -- Task is waiting on an entry call.
169 -- Task is waiting to start the abortable part of an
170 -- asynchronous select statement.
173 -- Task is waiting on a select statement with only a delay
176 Master_Completion_Sleep
,
177 -- Master completion has two phases.
178 -- In Phase 1 the task is sleeping in Complete_Master
179 -- having completed a master within itself,
180 -- and is waiting for the tasks dependent on that master to become
181 -- terminated or waiting on a terminate Phase.
183 Master_Phase_2_Sleep
,
184 -- In Phase 2 the task is sleeping in Complete_Master
185 -- waiting for tasks on terminate alternatives to finish
188 -- The following are special uses of sleep, for server tasks
189 -- within the run-time system.
191 Interrupt_Server_Idle_Sleep
,
192 Interrupt_Server_Blocked_Interrupt_Sleep
,
197 -- The task has been held by Asynchronous_Task_Control.Hold_Task
199 Interrupt_Server_Blocked_On_Event_Flag
200 -- The task has been blocked on a system call waiting for the
205 (Simple_Call
, Conditional_Call
, Asynchronous_Call
, Timed_Call
);
207 type Select_Modes
is (Simple_Mode
, Else_Mode
, Terminate_Mode
, Delay_Mode
);
209 subtype Delay_Modes
is Integer;
211 -------------------------------
212 -- Entry related definitions --
213 -------------------------------
215 Null_Entry
: constant := 0;
217 Max_Entry
: constant := Integer'Last;
219 Interrupt_Entry
: constant := -2;
221 Cancelled_Entry
: constant := -1;
223 type Entry_Index
is range Interrupt_Entry
.. Max_Entry
;
225 Null_Task_Entry
: constant := Null_Entry
;
227 Max_Task_Entry
: constant := Max_Entry
;
229 type Task_Entry_Index
is new Entry_Index
230 range Null_Task_Entry
.. Max_Task_Entry
;
232 type Entry_Call_Record
;
234 type Entry_Call_Link
is access all Entry_Call_Record
;
236 type Entry_Queue
is record
237 Head
: Entry_Call_Link
;
238 Tail
: Entry_Call_Link
;
241 type Task_Entry_Queue_Array
is
242 array (Task_Entry_Index
range <>) of Entry_Queue
;
244 ----------------------------------
245 -- Entry_Call_Record definition --
246 ----------------------------------
248 type Entry_Call_State
is
250 -- the call is not abortable, and never can be
253 -- the call is not abortable, but may become so
256 -- the call is not abortable, but once was
259 -- the call is abortable
262 -- the call has been completed
265 -- the call was asynchronous, and was cancelled
268 -- Never_Abortable is used for calls that are made in a abort
269 -- deferred region (see ARM 9.8(5-11), 9.8 (20)).
270 -- Such a call is never abortable.
272 -- The Was_ vs. Not_Yet_ distinction is needed to decide whether it
273 -- is OK to advance into the abortable part of an async. select stmt.
274 -- That is allowed iff the mode is Now_ or Was_.
276 -- Done indicates the call has been completed, without cancellation,
277 -- or no call has been made yet at this ATC nesting level,
278 -- and so aborting the call is no longer an issue.
279 -- Completion of the call does not necessarily indicate "success";
280 -- the call may be returning an exception if Exception_To_Raise is
283 -- Cancelled indicates the call was cancelled,
284 -- and so aborting the call is no longer an issue.
286 -- The call is on an entry queue unless
287 -- State >= Done, in which case it may or may not be still Onqueue.
289 -- Please do not modify the order of the values, without checking
290 -- all uses of this type. We rely on partial "monotonicity" of
291 -- Entry_Call_Record.State to avoid locking when we access this
292 -- value for certain tests. In particular:
294 -- 1) Once State >= Done, we can rely that the call has been
295 -- completed. If State >= Done, it will not
296 -- change until the task does another entry call at this level.
298 -- 2) Once State >= Was_Abortable, we can rely that the call has
299 -- been queued abortably at least once, and so the check for
300 -- whether it is OK to advance to the abortable part of an
301 -- async. select statement does not need to lock anything.
303 type Restricted_Entry_Call_Record
is record
309 State
: Entry_Call_State
;
310 pragma Atomic
(State
);
311 -- Indicates part of the state of the call.
313 -- If the call is not on a queue, it should
314 -- only be accessed by Self, and Self does not need any
315 -- lock to modify this field.
316 -- Once the call is on a queue, the value should be
317 -- something other than Done unless it is cancelled, and access is
318 -- controller by the "server" of the queue -- i.e., the lock
319 -- of Checked_To_Protection (Call_Target)
320 -- if the call record is on the queue of a PO, or the lock
321 -- of Called_Target if the call is on the queue of a task.
322 -- See comments on type declaration for more details.
324 Uninterpreted_Data
: System
.Address
;
325 -- Data passed by the compiler.
327 Exception_To_Raise
: Ada
.Exceptions
.Exception_Id
;
328 -- The exception to raise once this call has been completed without
331 pragma Suppress_Initialization
(Restricted_Entry_Call_Record
);
333 ------------------------------------
334 -- Task related other definitions --
335 ------------------------------------
337 type Activation_Chain
is limited private;
339 type Activation_Chain_Access
is access all Activation_Chain
;
341 type Task_Procedure_Access
is access procedure (Arg
: System
.Address
);
343 type Access_Boolean
is access all Boolean;
345 ----------------------------------------------
346 -- Ada_Task_Control_Block (ATCB) definition --
347 ----------------------------------------------
349 -- Notes on protection (synchronization) of TRTS data structures.
351 -- Any field of the TCB can be written by the activator of a task when the
352 -- task is created, since no other task can access the new task's
353 -- state until creation is complete.
355 -- The protection for each field is described in a comment starting with
358 -- When a lock is used to protect an ATCB field, this lock is simply named.
360 -- Some protection is described in terms of tasks related to the
361 -- ATCB being protected. These are:
363 -- Self: The task which is controlled by this ATCB.
364 -- Acceptor: A task accepting a call from Self.
365 -- Caller: A task calling an entry of Self.
366 -- Parent: The task executing the master on which Self depends.
367 -- Dependent: A task dependent on Self.
368 -- Activator: The task that created Self and initiated its activation.
369 -- Created: A task created and activated by Self.
371 -- Note: The order of the fields is important to implement efficiently
372 -- tasking support under gdb.
373 -- Currently gdb relies on the order of the State, Parent, Base_Priority,
374 -- Task_Image, Call and LL fields.
376 ----------------------------------------------------------------------
377 -- Common ATCB section --
379 -- This section is used by all GNARL implementations (regular and --
381 ----------------------------------------------------------------------
383 type Common_ATCB
is record
385 pragma Atomic
(State
);
386 -- Encodes some basic information about the state of a task,
387 -- including whether it has been activated, whether it is sleeping,
388 -- and whether it is terminated.
389 -- Protection: Self.L.
392 -- The task on which this task depends.
393 -- See also Master_Level and Master_Within.
395 Base_Priority
: System
.Any_Priority
;
396 -- Base priority, not changed during entry calls, only changed
397 -- via dynamic priorities package.
398 -- Protection: Only written by Self, accessed by anyone.
400 Current_Priority
: System
.Any_Priority
;
401 -- Active priority, except that the effects of protected object
402 -- priority ceilings are not reflected. This only reflects explicit
403 -- priority changes and priority inherited through task activation
406 -- Ada 95 notes: In Ada 95, this field will be transferred to the
407 -- Priority field of an Entry_Calls component when an entry call
408 -- is initiated. The Priority of the Entry_Calls component will not
409 -- change for the duration of the call. The accepting task can
410 -- use it to boost its own priority without fear of its changing in
413 -- This can safely be used in the priority ordering
414 -- of entry queues. Once a call is queued, its priority does not
417 -- Since an entry call cannot be made while executing
418 -- a protected action, the priority of a task will never reflect a
419 -- priority ceiling change at the point of an entry call.
421 -- Protection: Only written by Self, and only accessed when Acceptor
422 -- accepts an entry or when Created activates, at which points Self is
425 Task_Image
: System
.Task_Info
.Task_Image_Type
;
426 -- holds an access to string that provides a readable id for task,
427 -- built from the variable of which it is a value or component.
429 Call
: Entry_Call_Link
;
430 -- The entry call that has been accepted by this task.
431 -- Protection: Self.L. Self will modify this field
432 -- when Self.Accepting is False, and will not need the mutex to do so.
433 -- Once a task sets Pending_ATC_Level = 0, no other task can access
436 LL
: aliased Task_Primitives
.Private_Data
;
437 -- Control block used by the underlying low-level tasking
439 -- Protection: This is used only by the GNULLI implementation, which
440 -- takes care of all of its synchronization.
442 Task_Arg
: System
.Address
;
443 -- The argument to task procedure. Currently unused; this will
444 -- provide a handle for discriminant information.
445 -- Protection: Part of the synchronization between Self and
446 -- Activator. Activator writes it, once, before Self starts
447 -- executing. Thereafter, Self only reads it.
449 Task_Entry_Point
: Task_Procedure_Access
;
450 -- Information needed to call the procedure containing the code for
451 -- the body of this task.
452 -- Protection: Part of the synchronization between Self and
453 -- Activator. Activator writes it, once, before Self starts
454 -- executing. Self reads it, once, as part of its execution.
456 Compiler_Data
: System
.Soft_Links
.TSD
;
457 -- Task-specific data needed by the compiler to store
458 -- per-task structures.
459 -- Protection: Only accessed by Self.
461 All_Tasks_Link
: Task_ID
;
462 -- Used to link this task to the list of all tasks in the system.
463 -- Protection: RTS_Lock.
465 Activation_Link
: Task_ID
;
466 -- Used to link this task to a list of tasks to be activated.
467 -- Protection: Only used by Activator.
470 -- The task that created this task, either by declaring it as a task
471 -- object or by executing a task allocator.
472 -- The value is null iff Self has completed activation.
473 -- Protection: Set by Activator before Self is activated, and
474 -- only read and modified by Self after that.
476 Wait_Count
: Integer;
477 -- This count is used by a task that is waiting for other tasks.
478 -- At all other times, the value should be zero.
479 -- It is used differently in several different states.
480 -- Since a task cannot be in more than one of these states at the
481 -- same time, a single counter suffices.
482 -- Protection: Self.L.
486 -- This is the number of tasks that this task is activating, i.e. the
487 -- children that have started activation but have not completed it.
488 -- Protection: Self.L and Created.L. Both mutexes must be locked,
489 -- since Self.Activation_Count and Created.State must be synchronized.
491 -- Master_Completion_Sleep (phase 1)
493 -- This is the number dependent tasks of a master being
494 -- completed by Self that are not activated, not terminated, and
495 -- not waiting on a terminate alternative.
497 -- Master_Completion_2_Sleep (phase 2)
499 -- This is the count of tasks dependent on a master being
500 -- completed by Self which are waiting on a terminate alternative.
502 Elaborated
: Access_Boolean
;
503 -- Pointer to a flag indicating that this task's body has been
504 -- elaborated. The flag is created and managed by the
505 -- compiler-generated code.
506 -- Protection: The field itself is only accessed by Activator. The flag
507 -- that it points to is updated by Master and read by Activator; access
508 -- is assumed to be atomic.
510 Activation_Failed
: Boolean;
511 -- Set to True if activation of a chain of tasks fails,
512 -- so that the activator should raise Tasking_Error.
514 Task_Info
: System
.Task_Info
.Task_Info_Type
;
515 -- System-specific attributes of the task as specified by the
519 ---------------------------------------
520 -- Restricted_Ada_Task_Control_Block --
521 ---------------------------------------
523 -- This type should only be used by the restricted GNARLI and by
524 -- restricted GNULL implementations to allocate an ATCB (see
525 -- System.Task_Primitives.Operations.New_ATCB) that will take
526 -- significantly less memory.
527 -- Note that the restricted GNARLI should only access fields that are
528 -- present in the Restricted_Ada_Task_Control_Block structure.
530 type Restricted_Ada_Task_Control_Block
(Entry_Num
: Task_Entry_Index
) is
532 Common
: Common_ATCB
;
533 -- The common part between various tasking implementations
535 Entry_Call
: aliased Restricted_Entry_Call_Record
;
536 -- Protection: This field is used on entry call "queues" associated
537 -- with protected objects, and is protected by the protected object
540 pragma Suppress_Initialization
(Restricted_Ada_Task_Control_Block
);
542 Interrupt_Manager_ID
: Task_ID
;
543 -- This task ID is declared here to break circular dependencies.
544 -- Also declare Interrupt_Manager_ID after Task_ID is known, to avoid
545 -- generating unneeded finalization code.
547 -----------------------
548 -- List of all Tasks --
549 -----------------------
551 All_Tasks_List
: Task_ID
;
552 -- Global linked list of all tasks.
554 ------------------------------------------
555 -- Regular (non restricted) definitions --
556 ------------------------------------------
558 --------------------------------
559 -- Master Related Definitions --
560 --------------------------------
562 subtype Master_Level
is Integer;
563 subtype Master_ID
is Master_Level
;
565 -- Normally, a task starts out with internal master nesting level
566 -- one larger than external master nesting level. It is incremented
567 -- to one by Enter_Master, which is called in the task body only if
568 -- the compiler thinks the task may have dependent tasks. It is set to 1
569 -- for the environment task, the level 2 is reserved for server tasks of
570 -- the run-time system (the so called "independent tasks"), and the level
571 -- 3 is for the library level tasks.
573 Environment_Task_Level
: constant Master_Level
:= 1;
574 Independent_Task_Level
: constant Master_Level
:= 2;
575 Library_Task_Level
: constant Master_Level
:= 3;
577 ------------------------------
578 -- Task size, priority info --
579 ------------------------------
581 Unspecified_Priority
: constant Integer := System
.Priority
'First - 1;
583 Priority_Not_Boosted
: constant Integer := System
.Priority
'First - 1;
584 -- Definition of Priority actually has to come from the RTS configuration.
586 subtype Rendezvous_Priority
is Integer
587 range Priority_Not_Boosted
.. System
.Any_Priority
'Last;
589 ------------------------------------
590 -- Rendezvous related definitions --
591 ------------------------------------
593 No_Rendezvous
: constant := 0;
595 Max_Select
: constant Integer := Integer'Last;
598 subtype Select_Index
is Integer range No_Rendezvous
.. Max_Select
;
599 -- type Select_Index is range No_Rendezvous .. Max_Select;
601 subtype Positive_Select_Index
is
602 Select_Index
range 1 .. Select_Index
'Last;
604 type Accept_Alternative
is record
606 S
: Task_Entry_Index
;
610 array (Positive_Select_Index
range <>) of Accept_Alternative
;
612 type Accept_List_Access
is access constant Accept_List
;
614 -----------------------------------
615 -- ATC_Level related definitions --
616 -----------------------------------
618 Max_ATC_Nesting
: constant Natural := 20;
620 subtype ATC_Level_Base
is Integer range 0 .. Max_ATC_Nesting
;
622 ATC_Level_Infinity
: constant ATC_Level_Base
:= ATC_Level_Base
'Last;
624 subtype ATC_Level
is ATC_Level_Base
range 0 .. ATC_Level_Base
'Last - 1;
626 subtype ATC_Level_Index
is ATC_Level
range 1 .. ATC_Level
'Last;
628 ----------------------------------
629 -- Entry_Call_Record definition --
630 ----------------------------------
632 type Entry_Call_Record
is record
638 State
: Entry_Call_State
;
639 pragma Atomic
(State
);
640 -- Indicates part of the state of the call.
642 -- If the call is not on a queue, it should
643 -- only be accessed by Self, and Self does not need any
644 -- lock to modify this field.
645 -- Once the call is on a queue, the value should be
646 -- something other than Done unless it is cancelled, and access is
647 -- controller by the "server" of the queue -- i.e., the lock
648 -- of Checked_To_Protection (Call_Target)
649 -- if the call record is on the queue of a PO, or the lock
650 -- of Called_Target if the call is on the queue of a task.
651 -- See comments on type declaration for more details.
653 Uninterpreted_Data
: System
.Address
;
654 -- Data passed by the compiler.
656 Exception_To_Raise
: Ada
.Exceptions
.Exception_Id
;
657 -- The exception to raise once this call has been completed without
660 Prev
: Entry_Call_Link
;
662 Next
: Entry_Call_Link
;
665 -- One of Self and Level are redundant in this implementation, since
666 -- each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must
667 -- have access to the entry call record to be reading this, we could
668 -- get Self from Level, or Level from Self. However, this requires
669 -- non-portable address arithmetic.
673 Prio
: System
.Any_Priority
;
675 -- The above fields are those that there may be some hope of packing.
676 -- They are gathered together to allow for compilers that lay records
677 -- out contiguously, to allow for such packing.
679 Called_Task
: Task_ID
;
680 pragma Atomic
(Called_Task
);
681 -- Use for task entry calls.
682 -- The value is null if the call record is not in use.
683 -- Conversely, unless State is Done and Onqueue is false,
684 -- Called_Task points to an ATCB.
685 -- Protection: Called_Task.L.
687 Called_PO
: System
.Address
;
688 pragma Atomic
(Called_PO
);
689 -- Similar to Called_Task but for protected objects.
690 -- Note that the previous implementation tried to merge both
691 -- Called_Task and Called_PO but this ended up in many unexpected
692 -- complications (e.g having to add a magic number in the ATCB, which
693 -- caused gdb lots of confusion) with no real gain since the Lock_Server
694 -- implementation still need to loop around chasing for pointer changes
695 -- even with a single pointer.
697 Acceptor_Prev_Call
: Entry_Call_Link
;
698 -- For task entry calls only.
700 Acceptor_Prev_Priority
: Rendezvous_Priority
:= Priority_Not_Boosted
;
701 -- For task entry calls only.
702 -- The priority of the most recent prior call being serviced.
703 -- For protected entry calls, this function should be performed by
704 -- GNULLI ceiling locking.
706 Cancellation_Attempted
: Boolean := False;
707 pragma Atomic
(Cancellation_Attempted
);
708 -- Cancellation of the call has been attempted.
709 -- If it has succeeded, State = Cancelled.
711 -- Consider merging this into State?
713 Requeue_With_Abort
: Boolean := False;
714 -- Temporary to tell caller whether requeue is with abort.
716 -- Find a better way of doing this.
718 Needs_Requeue
: Boolean := False;
719 -- Temporary to tell acceptor of task entry call that
720 -- Exceptional_Complete_Rendezvous needs to do requeue.
723 ------------------------------------
724 -- Task related other definitions --
725 ------------------------------------
727 type Access_Address
is access all System
.Address
;
729 ----------------------------------------------
730 -- Ada_Task_Control_Block (ATCB) definition --
731 ----------------------------------------------
733 type Entry_Call_Array
is array (ATC_Level_Index
) of
734 aliased Entry_Call_Record
;
736 D_I_Count
: constant := 2;
737 -- This constant may be adjusted, to allow more Address-sized
738 -- attributes to be stored directly in the task control block.
740 subtype Direct_Index
is Integer range 0 .. D_I_Count
- 1;
741 -- Attributes with indices in this range are stored directly in
742 -- the task control block. Such attributes must be Address-sized.
743 -- Other attributes will be held in dynamically allocated records
744 -- chained off of the task control block.
746 type Direct_Attribute_Array
is
747 array (Direct_Index
) of aliased System
.Address
;
749 type Direct_Index_Vector
is mod 2 ** D_I_Count
;
750 -- This is a bit-vector type, used to store information about
751 -- the usage of the direct attribute fields.
753 type Task_Serial_Number
is mod 2 ** 64;
754 -- Used to give each task a unique serial number.
756 type Ada_Task_Control_Block
(Entry_Num
: Task_Entry_Index
) is record
757 Common
: Common_ATCB
;
758 -- The common part between various tasking implementations
760 Entry_Calls
: Entry_Call_Array
;
761 -- An array of entry calls.
762 -- Protection: The elements of this array are on entry call queues
763 -- associated with protected objects or task entries, and are protected
764 -- by the protected object lock or Acceptor.L, respectively.
766 New_Base_Priority
: System
.Any_Priority
;
767 -- New value for Base_Priority (for dynamic priorities package).
768 -- Protection: Self.L.
770 Global_Task_Lock_Nesting
: Natural := 0;
771 -- This is the current nesting level of calls to
772 -- System.Tasking.Stages.Lock_Task_T.
773 -- This allows a task to call Lock_Task_T multiple times without
774 -- deadlocking. A task only locks All_Task_Lock when its
775 -- All_Tasks_Nesting goes from 0 to 1, and only unlocked when it
777 -- Protection: Only accessed by Self.
779 Open_Accepts
: Accept_List_Access
;
780 -- This points to the Open_Accepts array of accept alternatives passed
781 -- to the RTS by the compiler-generated code to Selective_Wait.
782 -- It is non-null iff this task is ready to accept an entry call.
783 -- Protection: Self.L.
785 Chosen_Index
: Select_Index
;
786 -- The index in Open_Accepts of the entry call accepted by a selective
787 -- wait executed by this task.
788 -- Protection: Written by both Self and Caller. Usually protected
789 -- by Self.L. However, once the selection is known to have been
790 -- written it can be accessed without protection. This happens
791 -- after Self has updated it itself using information from a suspended
792 -- Caller, or after Caller has updated it and awakened Self.
794 Master_of_Task
: Master_Level
;
795 -- The task executing the master of this task, and the ID of this task's
796 -- master (unique only among masters currently active within Parent).
797 -- Protection: Set by Activator before Self is activated, and
798 -- read after Self is activated.
800 Master_Within
: Master_Level
;
801 -- The ID of the master currently executing within this task; that is,
802 -- the most deeply nested currently active master.
803 -- Protection: Only written by Self, and only read by Self or by
804 -- dependents when Self is attempting to exit a master. Since Self
805 -- will not write this field until the master is complete, the
806 -- synchronization should be adequate to prevent races.
808 Alive_Count
: Integer := 0;
809 -- Number of tasks directly dependent on this task (including itself)
810 -- that are still "alive", i.e. not terminated.
811 -- Protection: Self.L.
813 Awake_Count
: Integer := 0;
814 -- Number of tasks directly dependent on this task (including itself)
815 -- still "awake", i.e., are not terminated and not waiting on a
816 -- terminate alternative.
817 -- Invariant: Awake_Count <= Alive_Count
818 -- Protection: Self.L.
820 -- beginning of flags
822 Aborting
: Boolean := False;
823 pragma Atomic
(Aborting
);
824 -- Self is in the process of aborting. While set, prevents multiple
825 -- abortion signals from being sent by different aborter while abortion
826 -- is acted upon. This is essential since an aborter which calls
827 -- Abort_To_Level could set the Pending_ATC_Level to yet a lower level
828 -- (than the current level), may be preempted and would send the
829 -- abortion signal when resuming execution. At this point, the abortee
830 -- may have completed abortion to the proper level such that the
831 -- signal (and resulting abortion exception) are not handled any more.
832 -- In other words, the flag prevents a race between multiple aborters
834 -- Protection: Self.L.
836 ATC_Hack
: Boolean := False;
837 pragma Atomic
(ATC_Hack
);
839 -- Temporary fix, to allow Undefer_Abort to reset Aborting in the
840 -- handler for Abort_Signal that encloses an async. entry call.
841 -- For the longer term, this should be done via code in the
844 Callable
: Boolean := True;
845 -- It is OK to call entries of this task.
847 Dependents_Aborted
: Boolean := False;
848 -- This is set to True by whichever task takes responsibility
849 -- for aborting the dependents of this task.
850 -- Protection: Self.L.
852 Interrupt_Entry
: Boolean := False;
853 -- Indicates if one or more Interrupt Entries are attached to
854 -- the task. This flag is needed for cleaning up the Interrupt
857 Pending_Action
: Boolean := False;
858 -- Unified flag indicating some action needs to be take when abort
859 -- next becomes undeferred. Currently set if:
860 -- . Pending_Priority_Change is set
861 -- . Pending_ATC_Level is changed
862 -- . Requeue involving POs
863 -- (Abortable field may have changed and the Wait_Until_Abortable
864 -- has to recheck the abortable status of the call.)
865 -- . Exception_To_Raise is non-null
866 -- Protection: Self.L.
867 -- This should never be reset back to False outside of the
868 -- procedure Do_Pending_Action, which is called by Undefer_Abort.
869 -- It should only be set to True by Set_Priority and Abort_To_Level.
871 Pending_Priority_Change
: Boolean := False;
872 -- Flag to indicate pending priority change (for dynamic priorities
873 -- package). The base priority is updated on the next abortion
874 -- completion point (aka. synchronization point).
875 -- Protection: Self.L.
877 Terminate_Alternative
: Boolean := False;
878 -- Task is accepting Select with Terminate Alternative.
879 -- Protection: Self.L.
883 -- beginning of counts
885 ATC_Nesting_Level
: ATC_Level
:= 1;
886 -- The dynamic level of ATC nesting (currently executing nested
887 -- asynchronous select statements) in this task.
888 -- Protection: Self_ID.L.
889 -- Only Self reads or updates this field.
890 -- Decrementing it deallocates an Entry_Calls component, and care must
891 -- be taken that all references to that component are eliminated
892 -- before doing the decrement. This in turn will require locking
893 -- a protected object (for a protected entry call) or the Acceptor's
894 -- lock (for a task entry call).
895 -- No other task should attempt to read or modify this value.
897 Deferral_Level
: Natural := 1;
898 -- This is the number of times that Defer_Abortion has been called by
899 -- this task without a matching Undefer_Abortion call. Abortion is
900 -- only allowed when this zero.
901 -- It is initially 1, to protect the task at startup.
902 -- Protection: Only updated by Self; access assumed to be atomic.
904 Pending_ATC_Level
: ATC_Level_Base
:= ATC_Level_Infinity
;
905 -- The ATC level to which this task is currently being aborted.
906 -- If the value is zero, the entire task has "completed".
907 -- That may be via abort, exception propagation, or normal exit.
908 -- If the value is ATC_Level_Infinity, the task is not being
909 -- aborted to any level.
910 -- If the value is positive, the task has not completed.
911 -- This should ONLY be modified by
912 -- Abort_To_Level and Exit_One_ATC_Level.
913 -- Protection: Self.L.
915 Serial_Number
: Task_Serial_Number
;
916 -- A growing number to provide some way to check locking
919 Known_Tasks_Index
: Integer := -1;
920 -- Index in the System.Tasking.Debug.Known_Tasks array.
922 User_State
: Integer := 0;
923 -- user-writeable location, for use in debugging tasks;
924 -- debugger can display this value to show where the task currently
927 Direct_Attributes
: Direct_Attribute_Array
;
928 -- For task attributes that have same size as Address
930 Is_Defined
: Direct_Index_Vector
:= 0;
931 -- Bit I is 1 iff Direct_Attributes (I) is defined
933 Indirect_Attributes
: Access_Address
;
934 -- A pointer to chain of records for other attributes that
935 -- are not address-sized, including all tagged types.
937 Entry_Queues
: Task_Entry_Queue_Array
(1 .. Entry_Num
);
938 -- An array of task entry queues.
939 -- Protection: Self.L. Once a task has set Self.Stage to Completing, it
940 -- has exclusive access to this field.
942 pragma Volatile
(Ada_Task_Control_Block
);
944 ---------------------
945 -- Initialize_ATCB --
946 ---------------------
948 procedure Initialize_ATCB
950 Task_Entry_Point
: Task_Procedure_Access
;
951 Task_Arg
: System
.Address
;
953 Elaborated
: Access_Boolean
;
954 Base_Priority
: System
.Any_Priority
;
955 Task_Info
: System
.Task_Info
.Task_Info_Type
;
956 Stack_Size
: System
.Parameters
.Size_Type
;
958 Success
: out Boolean);
959 -- Initialize fields of a TCB and link into global TCB structures
960 -- Call this only with abort deferred and holding RTS_Lock.
964 Null_Task
: constant Task_ID
:= null;
966 type Activation_Chain
is record
969 pragma Volatile
(Activation_Chain
);
971 -- Activation_chain is an in-out parameter of initialization procedures
972 -- and it must be passed by reference because the init_proc may terminate
973 -- abnormally after creating task components, and these must be properly
974 -- registered for removal (Expunge_Unactivated_Tasks).