1 ------------------------------------------------------------------------------
3 -- GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- S Y S T E M . T A S K I N G --
11 -- Copyright (C) 1992-2001, Free Software Foundation, Inc. --
13 -- GNARL is free software; you can redistribute it and/or modify it under --
14 -- terms of the GNU General Public License as published by the Free Soft- --
15 -- ware Foundation; either version 2, or (at your option) any later ver- --
16 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
17 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
18 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
19 -- for more details. You should have received a copy of the GNU General --
20 -- Public License distributed with GNARL; see file COPYING. If not, write --
21 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
22 -- MA 02111-1307, USA. --
24 -- As a special exception, if other files instantiate generics from this --
25 -- unit, or you link this unit with other files to produce an executable, --
26 -- this unit does not by itself cause the resulting executable to be --
27 -- covered by the GNU General Public License. This exception does not --
28 -- however invalidate any other reasons why the executable file might be --
29 -- covered by the GNU Public License. --
31 -- GNARL was developed by the GNARL team at Florida State University. It is --
32 -- now maintained by Ada Core Technologies Inc. in cooperation with Florida --
33 -- State University (http://www.gnat.com). --
35 ------------------------------------------------------------------------------
37 -- This package provides necessary type definitions for compiler interface.
39 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
40 -- Any changes to this interface may require corresponding compiler changes.
43 -- Used for: Exception_Id
45 with System.Parameters;
48 with System.Task_Info;
49 -- used for Task_Info_Type, Task_Image_Type
51 with System.Soft_Links;
54 with System.Task_Primitives;
55 -- used for Private_Data
56 -- Lock (in System.Tasking.Protected_Objects)
58 with Unchecked_Conversion;
60 package System.Tasking is
62 -- -------------------
63 -- -- Locking Rules --
64 -- -------------------
66 -- The following rules must be followed at all times, to prevent
67 -- deadlock and generally ensure correct operation of locking.
69 -- . Never lock a lock unless abort is deferred.
71 -- . Never undefer abort while holding a lock.
73 -- . Overlapping critical sections must be properly nested,
74 -- and locks must be released in LIFO order.
75 -- e.g., the following is not allowed:
85 -- Locks with lower (smaller) level number cannot be locked
86 -- while holding a lock with a higher level number. (The level
87 -- number is the number at the left.)
89 -- 1. System.Tasking.PO_Simple.Protection.L (any PO lock)
90 -- 2. System.Tasking.Initialization.Global_Task_Lock (in body)
91 -- 3. System.Tasking.Task_Attributes.All_Attrs_L
92 -- 4. System.Task_Primitives.Operations.All_Tasks_L
93 -- 5. System.Interrupts.L (in body)
94 -- 6. System.Tasking.Ada_Task_Control_Block.LL.L (any TCB lock)
96 -- Clearly, there can be no circular chain of hold-and-wait
97 -- relationships involving locks in different ordering levels.
99 -- We used to have Global_Task_Lock before Protection.L but this was
100 -- clearly wrong since there can be calls to "new" inside protected
101 -- operations. The new ordering prevents these failures.
103 -- Sometime we need to hold two ATCB locks at the same time. To allow
104 -- us to order the locking, each ATCB is given a unique serial
105 -- number. If one needs to hold locks on several ATCBs at once,
106 -- the locks with lower serial numbers must be locked first.
108 -- We don't always need to check the serial numbers, since
109 -- the serial numbers are assigned sequentially, and so:
111 -- . The parent of a task always has a lower serial number.
112 -- . The activator of a task always has a lower serial number.
113 -- . The environment task has a lower serial number than any other task.
114 -- . If the activator of a task is different from the task's parent,
115 -- the parent always has a lower serial number than the activator.
117 -- For interrupt-handler state, we have a special locking rule.
118 -- See System.Interrupts (spec) for explanation.
120 ---------------------------------
121 -- Task_ID related definitions --
122 ---------------------------------
124 type Ada_Task_Control_Block;
126 type Task_ID is access all Ada_Task_Control_Block;
128 Null_Task : constant Task_ID;
130 type Task_List is array (Positive range <>) of Task_ID;
132 function Self return Task_ID;
133 pragma Inline (Self);
134 -- This is the compiler interface version of this function. Do not call
135 -- from the run-time system.
137 function To_Task_Id is new Unchecked_Conversion (System.Address, Task_ID);
138 function To_Address is new Unchecked_Conversion (Task_ID, System.Address);
140 -----------------------
141 -- Enumeration types --
142 -----------------------
146 -- Task has been created but has not been activated.
147 -- It cannot be executing.
150 -- For all states from here down, the task has been activated.
151 -- For all states from here down, except for Terminated, the task
153 -- Activator = null iff it has not yet completed activating.
155 -- For all states from here down,
156 -- the task has been activated, and may be executing.
159 -- Task is not blocked for any reason known to Ada.
160 -- (It may be waiting for a mutex, though.)
161 -- It is conceptually "executing" in normal mode.
164 -- The task is terminated, in the sense of ARM 9.3 (5).
165 -- Any dependents that were waiting on terminate
166 -- alternatives have been awakened and have terminated themselves.
169 -- Task is waiting for created tasks to complete activation.
172 -- Task is waiting on an accept or selective wait statement.
175 -- Task is waiting on an entry call.
178 -- Task is waiting to start the abortable part of an
179 -- asynchronous select statement.
182 -- Task is waiting on a select statement with only a delay
185 Master_Completion_Sleep,
186 -- Master completion has two phases.
187 -- In Phase 1 the task is sleeping in Complete_Master
188 -- having completed a master within itself,
189 -- and is waiting for the tasks dependent on that master to become
190 -- terminated or waiting on a terminate Phase.
192 Master_Phase_2_Sleep,
193 -- In Phase 2 the task is sleeping in Complete_Master
194 -- waiting for tasks on terminate alternatives to finish
197 -- The following are special uses of sleep, for server tasks
198 -- within the run-time system.
200 Interrupt_Server_Idle_Sleep,
201 Interrupt_Server_Blocked_Interrupt_Sleep,
206 -- The task has been held by Asynchronous_Task_Control.Hold_Task
208 Interrupt_Server_Blocked_On_Event_Flag
209 -- The task has been blocked on a system call waiting for the
214 (Simple_Call, Conditional_Call, Asynchronous_Call, Timed_Call);
216 type Select_Modes is (Simple_Mode, Else_Mode, Terminate_Mode, Delay_Mode);
218 subtype Delay_Modes is Integer;
220 -------------------------------
221 -- Entry related definitions --
222 -------------------------------
224 Null_Entry : constant := 0;
226 Max_Entry : constant := Integer'Last;
228 Interrupt_Entry : constant := -2;
230 Cancelled_Entry : constant := -1;
232 type Entry_Index is range Interrupt_Entry .. Max_Entry;
234 Null_Task_Entry : constant := Null_Entry;
236 Max_Task_Entry : constant := Max_Entry;
238 type Task_Entry_Index is new Entry_Index
239 range Null_Task_Entry .. Max_Task_Entry;
241 type Entry_Call_Record;
243 type Entry_Call_Link is access all Entry_Call_Record;
245 type Entry_Queue is record
246 Head : Entry_Call_Link;
247 Tail : Entry_Call_Link;
250 type Task_Entry_Queue_Array is
251 array (Task_Entry_Index range <>) of Entry_Queue;
253 ----------------------------------
254 -- Entry_Call_Record definition --
255 ----------------------------------
257 type Entry_Call_State is
259 -- the call is not abortable, and never can be
262 -- the call is not abortable, but may become so
265 -- the call is not abortable, but once was
268 -- the call is abortable
271 -- the call has been completed
274 -- the call was asynchronous, and was cancelled
277 -- Never_Abortable is used for calls that are made in a abort
278 -- deferred region (see ARM 9.8(5-11), 9.8 (20)).
279 -- Such a call is never abortable.
281 -- The Was_ vs. Not_Yet_ distinction is needed to decide whether it
282 -- is OK to advance into the abortable part of an async. select stmt.
283 -- That is allowed iff the mode is Now_ or Was_.
285 -- Done indicates the call has been completed, without cancellation,
286 -- or no call has been made yet at this ATC nesting level,
287 -- and so aborting the call is no longer an issue.
288 -- Completion of the call does not necessarily indicate "success";
289 -- the call may be returning an exception if Exception_To_Raise is
292 -- Cancelled indicates the call was cancelled,
293 -- and so aborting the call is no longer an issue.
295 -- The call is on an entry queue unless
296 -- State >= Done, in which case it may or may not be still Onqueue.
298 -- Please do not modify the order of the values, without checking
299 -- all uses of this type. We rely on partial "monotonicity" of
300 -- Entry_Call_Record.State to avoid locking when we access this
301 -- value for certain tests. In particular:
303 -- 1) Once State >= Done, we can rely that the call has been
304 -- completed. If State >= Done, it will not
305 -- change until the task does another entry call at this level.
307 -- 2) Once State >= Was_Abortable, we can rely that the call has
308 -- been queued abortably at least once, and so the check for
309 -- whether it is OK to advance to the abortable part of an
310 -- async. select statement does not need to lock anything.
312 type Restricted_Entry_Call_Record is record
318 State : Entry_Call_State;
319 pragma Atomic (State);
320 -- Indicates part of the state of the call.
322 -- If the call is not on a queue, it should
323 -- only be accessed by Self, and Self does not need any
324 -- lock to modify this field.
325 -- Once the call is on a queue, the value should be
326 -- something other than Done unless it is cancelled, and access is
327 -- controller by the "server" of the queue -- i.e., the lock
328 -- of Checked_To_Protection (Call_Target)
329 -- if the call record is on the queue of a PO, or the lock
330 -- of Called_Target if the call is on the queue of a task.
331 -- See comments on type declaration for more details.
333 Uninterpreted_Data : System.Address;
334 -- Data passed by the compiler.
336 Exception_To_Raise : Ada.Exceptions.Exception_Id;
337 -- The exception to raise once this call has been completed without
340 pragma Suppress_Initialization (Restricted_Entry_Call_Record);
342 ------------------------------------
343 -- Task related other definitions --
344 ------------------------------------
346 type Activation_Chain is limited private;
348 type Activation_Chain_Access is access all Activation_Chain;
350 type Task_Procedure_Access is access procedure (Arg : System.Address);
352 type Access_Boolean is access all Boolean;
354 ----------------------------------------------
355 -- Ada_Task_Control_Block (ATCB) definition --
356 ----------------------------------------------
358 -- Notes on protection (synchronization) of TRTS data structures.
360 -- Any field of the TCB can be written by the activator of a task when the
361 -- task is created, since no other task can access the new task's
362 -- state until creation is complete.
364 -- The protection for each field is described in a comment starting with
367 -- When a lock is used to protect an ATCB field, this lock is simply named.
369 -- Some protection is described in terms of tasks related to the
370 -- ATCB being protected. These are:
372 -- Self: The task which is controlled by this ATCB.
373 -- Acceptor: A task accepting a call from Self.
374 -- Caller: A task calling an entry of Self.
375 -- Parent: The task executing the master on which Self depends.
376 -- Dependent: A task dependent on Self.
377 -- Activator: The task that created Self and initiated its activation.
378 -- Created: A task created and activated by Self.
380 -- Note: The order of the fields is important to implement efficiently
381 -- tasking support under gdb.
382 -- Currently gdb relies on the order of the State, Parent, Base_Priority,
383 -- Task_Image, Call and LL fields.
385 ----------------------------------------------------------------------
386 -- Common ATCB section --
388 -- This section is used by all GNARL implementations (regular and --
390 ----------------------------------------------------------------------
392 type Common_ATCB is record
394 pragma Atomic (State);
395 -- Encodes some basic information about the state of a task,
396 -- including whether it has been activated, whether it is sleeping,
397 -- and whether it is terminated.
398 -- Protection: Self.L.
401 -- The task on which this task depends.
402 -- See also Master_Level and Master_Within.
404 Base_Priority : System.Any_Priority;
405 -- Base priority, not changed during entry calls, only changed
406 -- via dynamic priorities package.
407 -- Protection: Only written by Self, accessed by anyone.
409 Current_Priority : System.Any_Priority;
410 -- Active priority, except that the effects of protected object
411 -- priority ceilings are not reflected. This only reflects explicit
412 -- priority changes and priority inherited through task activation
415 -- Ada 95 notes: In Ada 95, this field will be transferred to the
416 -- Priority field of an Entry_Calls component when an entry call
417 -- is initiated. The Priority of the Entry_Calls component will not
418 -- change for the duration of the call. The accepting task can
419 -- use it to boost its own priority without fear of its changing in
422 -- This can safely be used in the priority ordering
423 -- of entry queues. Once a call is queued, its priority does not
426 -- Since an entry call cannot be made while executing
427 -- a protected action, the priority of a task will never reflect a
428 -- priority ceiling change at the point of an entry call.
430 -- Protection: Only written by Self, and only accessed when Acceptor
431 -- accepts an entry or when Created activates, at which points Self is
434 Task_Image : System.Task_Info.Task_Image_Type;
435 -- holds an access to string that provides a readable id for task,
436 -- built from the variable of which it is a value or component.
438 Call : Entry_Call_Link;
439 -- The entry call that has been accepted by this task.
440 -- Protection: Self.L. Self will modify this field
441 -- when Self.Accepting is False, and will not need the mutex to do so.
442 -- Once a task sets Pending_ATC_Level = 0, no other task can access
445 LL : aliased Task_Primitives.Private_Data;
446 -- Control block used by the underlying low-level tasking
448 -- Protection: This is used only by the GNULLI implementation, which
449 -- takes care of all of its synchronization.
451 Task_Arg : System.Address;
452 -- The argument to task procedure. Currently unused; this will
453 -- provide a handle for discriminant information.
454 -- Protection: Part of the synchronization between Self and
455 -- Activator. Activator writes it, once, before Self starts
456 -- executing. Thereafter, Self only reads it.
458 Task_Entry_Point : Task_Procedure_Access;
459 -- Information needed to call the procedure containing the code for
460 -- the body of this task.
461 -- Protection: Part of the synchronization between Self and
462 -- Activator. Activator writes it, once, before Self starts
463 -- executing. Self reads it, once, as part of its execution.
465 Compiler_Data : System.Soft_Links.TSD;
466 -- Task-specific data needed by the compiler to store
467 -- per-task structures.
468 -- Protection: Only accessed by Self.
470 All_Tasks_Link : Task_ID;
471 -- Used to link this task to the list of all tasks in the system.
472 -- Protection: All_Tasks.L.
474 Activation_Link : Task_ID;
475 -- Used to link this task to a list of tasks to be activated.
476 -- Protection: Only used by Activator.
479 -- The task that created this task, either by declaring it as a task
480 -- object or by executing a task allocator.
481 -- The value is null iff Self has completed activation.
482 -- Protection: Set by Activator before Self is activated, and
483 -- only read and modified by Self after that.
485 Wait_Count : Integer;
486 -- This count is used by a task that is waiting for other tasks.
487 -- At all other times, the value should be zero.
488 -- It is used differently in several different states.
489 -- Since a task cannot be in more than one of these states at the
490 -- same time, a single counter suffices.
491 -- Protection: Self.L.
495 -- This is the number of tasks that this task is activating, i.e. the
496 -- children that have started activation but have not completed it.
497 -- Protection: Self.L and Created.L. Both mutexes must be locked,
498 -- since Self.Activation_Count and Created.State must be synchronized.
500 -- Master_Completion_Sleep (phase 1)
502 -- This is the number dependent tasks of a master being
503 -- completed by Self that are not activated, not terminated, and
504 -- not waiting on a terminate alternative.
506 -- Master_Completion_2_Sleep (phase 2)
508 -- This is the count of tasks dependent on a master being
509 -- completed by Self which are waiting on a terminate alternative.
511 Elaborated : Access_Boolean;
512 -- Pointer to a flag indicating that this task's body has been
513 -- elaborated. The flag is created and managed by the
514 -- compiler-generated code.
515 -- Protection: The field itself is only accessed by Activator. The flag
516 -- that it points to is updated by Master and read by Activator; access
517 -- is assumed to be atomic.
519 Activation_Failed : Boolean;
520 -- Set to True if activation of a chain of tasks fails,
521 -- so that the activator should raise Tasking_Error.
523 Task_Info : System.Task_Info.Task_Info_Type;
524 -- System-specific attributes of the task as specified by the
528 ---------------------------------------
529 -- Restricted_Ada_Task_Control_Block --
530 ---------------------------------------
532 -- This type should only be used by the restricted GNARLI and by
533 -- restricted GNULL implementations to allocate an ATCB (see
534 -- System.Task_Primitives.Operations.New_ATCB) that will take
535 -- significantly less memory.
536 -- Note that the restricted GNARLI should only access fields that are
537 -- present in the Restricted_Ada_Task_Control_Block structure.
539 type Restricted_Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is
541 Common : Common_ATCB;
542 -- The common part between various tasking implementations
544 Entry_Call : aliased Restricted_Entry_Call_Record;
545 -- Protection: This field is used on entry call "queues" associated
546 -- with protected objects, and is protected by the protected object
549 pragma Suppress_Initialization (Restricted_Ada_Task_Control_Block);
551 Interrupt_Manager_ID : Task_ID;
552 -- This task ID is declared here to break circular dependencies.
553 -- Also declare Interrupt_Manager_ID after Task_ID is known, to avoid
554 -- generating unneeded finalization code.
556 -----------------------
557 -- List of all Tasks --
558 -----------------------
560 All_Tasks_List : Task_ID;
561 -- Global linked list of all tasks.
563 ------------------------------------------
564 -- Regular (non restricted) definitions --
565 ------------------------------------------
567 --------------------------------
568 -- Master Related Definitions --
569 --------------------------------
571 subtype Master_Level is Integer;
572 subtype Master_ID is Master_Level;
574 -- Normally, a task starts out with internal master nesting level
575 -- one larger than external master nesting level. It is incremented
576 -- to one by Enter_Master, which is called in the task body only if
577 -- the compiler thinks the task may have dependent tasks. It is set to 1
578 -- for the environment task, the level 2 is reserved for server tasks of
579 -- the run-time system (the so called "independent tasks"), and the level
580 -- 3 is for the library level tasks.
582 Environment_Task_Level : constant Master_Level := 1;
583 Independent_Task_Level : constant Master_Level := 2;
584 Library_Task_Level : constant Master_Level := 3;
586 ------------------------------
587 -- Task size, priority info --
588 ------------------------------
590 Unspecified_Priority : constant Integer := System.Priority'First - 1;
592 Priority_Not_Boosted : constant Integer := System.Priority'First - 1;
593 -- Definition of Priority actually has to come from the RTS configuration.
595 subtype Rendezvous_Priority is Integer
596 range Priority_Not_Boosted .. System.Any_Priority'Last;
598 ------------------------------------
599 -- Rendezvous related definitions --
600 ------------------------------------
602 No_Rendezvous : constant := 0;
604 Max_Select : constant Integer := Integer'Last;
607 subtype Select_Index is Integer range No_Rendezvous .. Max_Select;
608 -- type Select_Index is range No_Rendezvous .. Max_Select;
610 subtype Positive_Select_Index is
611 Select_Index range 1 .. Select_Index'Last;
613 type Accept_Alternative is record
615 S : Task_Entry_Index;
619 array (Positive_Select_Index range <>) of Accept_Alternative;
621 type Accept_List_Access is access constant Accept_List;
623 -----------------------------------
624 -- ATC_Level related definitions --
625 -----------------------------------
627 Max_ATC_Nesting : constant Natural := 20;
629 subtype ATC_Level_Base is Integer range 0 .. Max_ATC_Nesting;
631 ATC_Level_Infinity : constant ATC_Level_Base := ATC_Level_Base'Last;
633 subtype ATC_Level is ATC_Level_Base range 0 .. ATC_Level_Base'Last - 1;
635 subtype ATC_Level_Index is ATC_Level range 1 .. ATC_Level'Last;
637 ----------------------------------
638 -- Entry_Call_Record definition --
639 ----------------------------------
641 type Entry_Call_Record is record
647 State : Entry_Call_State;
648 pragma Atomic (State);
649 -- Indicates part of the state of the call.
651 -- If the call is not on a queue, it should
652 -- only be accessed by Self, and Self does not need any
653 -- lock to modify this field.
654 -- Once the call is on a queue, the value should be
655 -- something other than Done unless it is cancelled, and access is
656 -- controller by the "server" of the queue -- i.e., the lock
657 -- of Checked_To_Protection (Call_Target)
658 -- if the call record is on the queue of a PO, or the lock
659 -- of Called_Target if the call is on the queue of a task.
660 -- See comments on type declaration for more details.
662 Uninterpreted_Data : System.Address;
663 -- Data passed by the compiler.
665 Exception_To_Raise : Ada.Exceptions.Exception_Id;
666 -- The exception to raise once this call has been completed without
669 Prev : Entry_Call_Link;
671 Next : Entry_Call_Link;
674 -- One of Self and Level are redundant in this implementation, since
675 -- each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must
676 -- have access to the entry call record to be reading this, we could
677 -- get Self from Level, or Level from Self. However, this requires
678 -- non-portable address arithmetic.
682 Prio : System.Any_Priority;
684 -- The above fields are those that there may be some hope of packing.
685 -- They are gathered together to allow for compilers that lay records
686 -- out contiguously, to allow for such packing.
688 Called_Task : Task_ID;
689 pragma Atomic (Called_Task);
690 -- Use for task entry calls.
691 -- The value is null if the call record is not in use.
692 -- Conversely, unless State is Done and Onqueue is false,
693 -- Called_Task points to an ATCB.
694 -- Protection: Called_Task.L.
696 Called_PO : System.Address;
697 pragma Atomic (Called_PO);
698 -- Similar to Called_Task but for protected objects.
699 -- Note that the previous implementation tried to merge both
700 -- Called_Task and Called_PO but this ended up in many unexpected
701 -- complications (e.g having to add a magic number in the ATCB, which
702 -- caused gdb lots of confusion) with no real gain since the Lock_Server
703 -- implementation still need to loop around chasing for pointer changes
704 -- even with a single pointer.
706 Acceptor_Prev_Call : Entry_Call_Link;
707 -- For task entry calls only.
709 Acceptor_Prev_Priority : Rendezvous_Priority := Priority_Not_Boosted;
710 -- For task entry calls only.
711 -- The priority of the most recent prior call being serviced.
712 -- For protected entry calls, this function should be performed by
713 -- GNULLI ceiling locking.
715 Cancellation_Attempted : Boolean := False;
716 pragma Atomic (Cancellation_Attempted);
717 -- Cancellation of the call has been attempted.
718 -- If it has succeeded, State = Cancelled.
720 -- Consider merging this into State?
722 Requeue_With_Abort : Boolean := False;
723 -- Temporary to tell caller whether requeue is with abort.
725 -- Find a better way of doing this.
727 Needs_Requeue : Boolean := False;
728 -- Temporary to tell acceptor of task entry call that
729 -- Exceptional_Complete_Rendezvous needs to do requeue.
732 ------------------------------------
733 -- Task related other definitions --
734 ------------------------------------
736 type Access_Address is access all System.Address;
738 ----------------------------------------------
739 -- Ada_Task_Control_Block (ATCB) definition --
740 ----------------------------------------------
742 type Entry_Call_Array is array (ATC_Level_Index) of
743 aliased Entry_Call_Record;
745 D_I_Count : constant := 2;
746 -- This constant may be adjusted, to allow more Address-sized
747 -- attributes to be stored directly in the task control block.
749 subtype Direct_Index is Integer range 0 .. D_I_Count - 1;
750 -- Attributes with indices in this range are stored directly in
751 -- the task control block. Such attributes must be Address-sized.
752 -- Other attributes will be held in dynamically allocated records
753 -- chained off of the task control block.
755 type Direct_Attribute_Array is
756 array (Direct_Index) of aliased System.Address;
758 type Direct_Index_Vector is mod 2 ** D_I_Count;
759 -- This is a bit-vector type, used to store information about
760 -- the usage of the direct attribute fields.
762 type Task_Serial_Number is mod 2 ** 64;
763 -- Used to give each task a unique serial number.
765 type Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is record
766 Common : Common_ATCB;
767 -- The common part between various tasking implementations
769 Entry_Calls : Entry_Call_Array;
770 -- An array of entry calls.
771 -- Protection: The elements of this array are on entry call queues
772 -- associated with protected objects or task entries, and are protected
773 -- by the protected object lock or Acceptor.L, respectively.
775 New_Base_Priority : System.Any_Priority;
776 -- New value for Base_Priority (for dynamic priorities package).
777 -- Protection: Self.L.
779 Global_Task_Lock_Nesting : Natural := 0;
780 -- This is the current nesting level of calls to
781 -- System.Tasking.Stages.Lock_Task_T.
782 -- This allows a task to call Lock_Task_T multiple times without
783 -- deadlocking. A task only locks All_Task_Lock when its
784 -- All_Tasks_Nesting goes from 0 to 1, and only unlocked when it
786 -- Protection: Only accessed by Self.
788 Open_Accepts : Accept_List_Access;
789 -- This points to the Open_Accepts array of accept alternatives passed
790 -- to the RTS by the compiler-generated code to Selective_Wait.
791 -- It is non-null iff this task is ready to accept an entry call.
792 -- Protection: Self.L.
794 Chosen_Index : Select_Index;
795 -- The index in Open_Accepts of the entry call accepted by a selective
796 -- wait executed by this task.
797 -- Protection: Written by both Self and Caller. Usually protected
798 -- by Self.L. However, once the selection is known to have been
799 -- written it can be accessed without protection. This happens
800 -- after Self has updated it itself using information from a suspended
801 -- Caller, or after Caller has updated it and awakened Self.
803 Master_of_Task : Master_Level;
804 -- The task executing the master of this task, and the ID of this task's
805 -- master (unique only among masters currently active within Parent).
806 -- Protection: Set by Activator before Self is activated, and
807 -- read after Self is activated.
809 Master_Within : Master_Level;
810 -- The ID of the master currently executing within this task; that is,
811 -- the most deeply nested currently active master.
812 -- Protection: Only written by Self, and only read by Self or by
813 -- dependents when Self is attempting to exit a master. Since Self
814 -- will not write this field until the master is complete, the
815 -- synchronization should be adequate to prevent races.
817 Alive_Count : Integer := 0;
818 -- Number of tasks directly dependent on this task (including itself)
819 -- that are still "alive", i.e. not terminated.
820 -- Protection: Self.L.
822 Awake_Count : Integer := 0;
823 -- Number of tasks directly dependent on this task (including itself)
824 -- still "awake", i.e., are not terminated and not waiting on a
825 -- terminate alternative.
826 -- Invariant: Awake_Count <= Alive_Count
827 -- Protection: Self.L.
829 -- beginning of flags
831 Aborting : Boolean := False;
832 pragma Atomic (Aborting);
833 -- Self is in the process of aborting. While set, prevents multiple
834 -- abortion signals from being sent by different aborter while abortion
835 -- is acted upon. This is essential since an aborter which calls
836 -- Abort_To_Level could set the Pending_ATC_Level to yet a lower level
837 -- (than the current level), may be preempted and would send the
838 -- abortion signal when resuming execution. At this point, the abortee
839 -- may have completed abortion to the proper level such that the
840 -- signal (and resulting abortion exception) are not handled any more.
841 -- In other words, the flag prevents a race between multiple aborters
843 -- Protection: Self.L.
845 ATC_Hack : Boolean := False;
846 pragma Atomic (ATC_Hack);
848 -- Temporary fix, to allow Undefer_Abort to reset Aborting in the
849 -- handler for Abort_Signal that encloses an async. entry call.
850 -- For the longer term, this should be done via code in the
853 Callable : Boolean := True;
854 -- It is OK to call entries of this task.
856 Dependents_Aborted : Boolean := False;
857 -- This is set to True by whichever task takes responsibility
858 -- for aborting the dependents of this task.
859 -- Protection: Self.L.
861 Interrupt_Entry : Boolean := False;
862 -- Indicates if one or more Interrupt Entries are attached to
863 -- the task. This flag is needed for cleaning up the Interrupt
866 Pending_Action : Boolean := False;
867 -- Unified flag indicating some action needs to be take when abort
868 -- next becomes undeferred. Currently set if:
869 -- . Pending_Priority_Change is set
870 -- . Pending_ATC_Level is changed
871 -- . Requeue involving POs
872 -- (Abortable field may have changed and the Wait_Until_Abortable
873 -- has to recheck the abortable status of the call.)
874 -- . Exception_To_Raise is non-null
875 -- Protection: Self.L.
876 -- This should never be reset back to False outside of the
877 -- procedure Do_Pending_Action, which is called by Undefer_Abort.
878 -- It should only be set to True by Set_Priority and Abort_To_Level.
880 Pending_Priority_Change : Boolean := False;
881 -- Flag to indicate pending priority change (for dynamic priorities
882 -- package). The base priority is updated on the next abortion
883 -- completion point (aka. synchronization point).
884 -- Protection: Self.L.
886 Terminate_Alternative : Boolean := False;
887 -- Task is accepting Select with Terminate Alternative.
888 -- Protection: Self.L.
892 -- beginning of counts
894 ATC_Nesting_Level : ATC_Level := 1;
895 -- The dynamic level of ATC nesting (currently executing nested
896 -- asynchronous select statements) in this task.
897 -- Protection: Self_ID.L.
898 -- Only Self reads or updates this field.
899 -- Decrementing it deallocates an Entry_Calls component, and care must
900 -- be taken that all references to that component are eliminated
901 -- before doing the decrement. This in turn will require locking
902 -- a protected object (for a protected entry call) or the Acceptor's
903 -- lock (for a task entry call).
904 -- No other task should attempt to read or modify this value.
906 Deferral_Level : Natural := 1;
907 -- This is the number of times that Defer_Abortion has been called by
908 -- this task without a matching Undefer_Abortion call. Abortion is
909 -- only allowed when this zero.
910 -- It is initially 1, to protect the task at startup.
911 -- Protection: Only updated by Self; access assumed to be atomic.
913 Pending_ATC_Level : ATC_Level_Base := ATC_Level_Infinity;
914 -- The ATC level to which this task is currently being aborted.
915 -- If the value is zero, the entire task has "completed".
916 -- That may be via abort, exception propagation, or normal exit.
917 -- If the value is ATC_Level_Infinity, the task is not being
918 -- aborted to any level.
919 -- If the value is positive, the task has not completed.
920 -- This should ONLY be modified by
921 -- Abort_To_Level and Exit_One_ATC_Level.
922 -- Protection: Self.L.
924 Serial_Number : Task_Serial_Number;
925 -- A growing number to provide some way to check locking
928 Known_Tasks_Index : Integer := -1;
929 -- Index in the System.Tasking.Debug.Known_Tasks array.
931 User_State : Integer := 0;
932 -- user-writeable location, for use in debugging tasks;
933 -- debugger can display this value to show where the task currently
936 Direct_Attributes : Direct_Attribute_Array;
937 -- for task attributes that have same size as Address
938 Is_Defined : Direct_Index_Vector := 0;
939 -- bit I is 1 iff Direct_Attributes (I) is defined
940 Indirect_Attributes : Access_Address;
941 -- a pointer to chain of records for other attributes that
942 -- are not address-sized, including all tagged types.
944 Entry_Queues : Task_Entry_Queue_Array (1 .. Entry_Num);
945 -- An array of task entry queues.
946 -- Protection: Self.L. Once a task has set Self.Stage to Completing, it
947 -- has exclusive access to this field.
949 pragma Volatile (Ada_Task_Control_Block);
951 ---------------------
952 -- Initialize_ATCB --
953 ---------------------
955 procedure Initialize_ATCB
957 Task_Entry_Point : Task_Procedure_Access;
958 Task_Arg : System.Address;
960 Elaborated : Access_Boolean;
961 Base_Priority : System.Any_Priority;
962 Task_Info : System.Task_Info.Task_Info_Type;
963 Stack_Size : System.Parameters.Size_Type;
965 Success : out Boolean);
966 -- Initialize fields of a TCB and link into global TCB structures
967 -- Call this only with abort deferred and holding All_Tasks_L.
971 Null_Task : constant Task_ID := null;
973 type Activation_Chain is record
976 pragma Volatile (Activation_Chain);
978 -- Activation_chain is an in-out parameter of initialization procedures
979 -- and it must be passed by reference because the init_proc may terminate
980 -- abnormally after creating task components, and these must be properly
981 -- registered for removal (Expunge_Unactivated_Tasks).