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-2005, 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
48 with System.Soft_Links;
51 with System.Task_Primitives;
52 -- used for Private_Data
54 with Unchecked_Conversion;
56 package System.Tasking is
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, and locks must
70 -- be released in LIFO order. e.g., the following is not allowed:
80 -- Locks with lower (smaller) level number cannot be locked
81 -- while holding a lock with a higher level number. (The level
83 -- 1. System.Tasking.PO_Simple.Protection.L (any PO lock)
84 -- 2. System.Tasking.Initialization.Global_Task_Lock (in body)
85 -- 3. System.Task_Primitives.Operations.Single_RTS_Lock
86 -- 4. System.Tasking.Ada_Task_Control_Block.LL.L (any TCB lock)
88 -- Clearly, there can be no circular chain of hold-and-wait
89 -- relationships involving locks in different ordering levels.
91 -- We used to have Global_Task_Lock before Protection.L but this was
92 -- clearly wrong since there can be calls to "new" inside protected
93 -- operations. The new ordering prevents these failures.
95 -- Sometimes we need to hold two ATCB locks at the same time. To allow us
96 -- to order the locking, each ATCB is given a unique serial number. If one
97 -- needs to hold locks on several ATCBs at once, the locks with lower
98 -- serial numbers must be locked first.
100 -- We don't always need to check the serial numbers, since the serial
101 -- numbers are assigned sequentially, and so:
103 -- . The parent of a task always has a lower serial number.
104 -- . The activator of a task always has a lower serial number.
105 -- . The environment task has a lower serial number than any other task.
106 -- . If the activator of a task is different from the task's parent,
107 -- the parent always has a lower serial number than the activator.
109 ---------------------------------
110 -- Task_Id related definitions --
111 ---------------------------------
113 type Ada_Task_Control_Block;
115 type Task_Id is access all Ada_Task_Control_Block;
117 Null_Task : constant Task_Id;
119 type Task_List is array (Positive range <>) of Task_Id;
121 function Self return Task_Id;
122 pragma Inline (Self);
123 -- This is the compiler interface version of this function. Do not call
124 -- from the run-time system.
126 function To_Task_Id is new Unchecked_Conversion (System.Address, Task_Id);
127 function To_Address is new Unchecked_Conversion (Task_Id, System.Address);
129 -----------------------
130 -- Enumeration types --
131 -----------------------
135 -- Task has been created but has not been activated.
136 -- It cannot be executing.
139 -- For all states from here down, the task has been activated.
140 -- For all states from here down, except for Terminated, the task
142 -- Activator = null iff it has not yet completed activating.
144 -- For all states from here down,
145 -- the task has been activated, and may be executing.
148 -- Task is not blocked for any reason known to Ada.
149 -- (It may be waiting for a mutex, though.)
150 -- It is conceptually "executing" in normal mode.
153 -- The task is terminated, in the sense of ARM 9.3 (5).
154 -- Any dependents that were waiting on terminate
155 -- alternatives have been awakened and have terminated themselves.
158 -- Task is waiting for created tasks to complete activation
161 -- Task is waiting on an accept or selective wait statement
164 -- Task is waiting on an entry call
167 -- Task is waiting to start the abortable part of an
168 -- asynchronous select statement.
171 -- Task is waiting on a select statement with only a delay
174 Master_Completion_Sleep,
175 -- Master completion has two phases.
176 -- In Phase 1 the task is sleeping in Complete_Master
177 -- having completed a master within itself,
178 -- and is waiting for the tasks dependent on that master to become
179 -- terminated or waiting on a terminate Phase.
181 Master_Phase_2_Sleep,
182 -- In Phase 2 the task is sleeping in Complete_Master
183 -- waiting for tasks on terminate alternatives to finish
186 -- The following are special uses of sleep, for server tasks
187 -- within the run-time system.
189 Interrupt_Server_Idle_Sleep,
190 Interrupt_Server_Blocked_Interrupt_Sleep,
195 -- The task has been held by Asynchronous_Task_Control.Hold_Task
197 Interrupt_Server_Blocked_On_Event_Flag
198 -- The task has been blocked on a system call waiting for the
203 (Simple_Call, Conditional_Call, Asynchronous_Call, Timed_Call);
205 type Select_Modes is (Simple_Mode, Else_Mode, Terminate_Mode, Delay_Mode);
207 subtype Delay_Modes is Integer;
209 -------------------------------
210 -- Entry related definitions --
211 -------------------------------
213 Null_Entry : constant := 0;
215 Max_Entry : constant := Integer'Last;
217 Interrupt_Entry : constant := -2;
219 Cancelled_Entry : constant := -1;
221 type Entry_Index is range Interrupt_Entry .. Max_Entry;
223 Null_Task_Entry : constant := Null_Entry;
225 Max_Task_Entry : constant := Max_Entry;
227 type Task_Entry_Index is new Entry_Index
228 range Null_Task_Entry .. Max_Task_Entry;
230 type Entry_Call_Record;
232 type Entry_Call_Link is access all Entry_Call_Record;
234 type Entry_Queue is record
235 Head : Entry_Call_Link;
236 Tail : Entry_Call_Link;
239 type Task_Entry_Queue_Array is
240 array (Task_Entry_Index range <>) of Entry_Queue;
242 ----------------------------------
243 -- Entry_Call_Record definition --
244 ----------------------------------
246 type Entry_Call_State is
248 -- the call is not abortable, and never can be
251 -- the call is not abortable, but may become so
254 -- the call is not abortable, but once was
257 -- the call is abortable
260 -- the call has been completed
263 -- the call was asynchronous, and was cancelled
266 -- Never_Abortable is used for calls that are made in a abort
267 -- deferred region (see ARM 9.8(5-11), 9.8 (20)).
268 -- Such a call is never abortable.
270 -- The Was_ vs. Not_Yet_ distinction is needed to decide whether it
271 -- is OK to advance into the abortable part of an async. select stmt.
272 -- That is allowed iff the mode is Now_ or Was_.
274 -- Done indicates the call has been completed, without cancellation,
275 -- or no call has been made yet at this ATC nesting level,
276 -- and so aborting the call is no longer an issue.
277 -- Completion of the call does not necessarily indicate "success";
278 -- the call may be returning an exception if Exception_To_Raise is
281 -- Cancelled indicates the call was cancelled,
282 -- and so aborting the call is no longer an issue.
284 -- The call is on an entry queue unless
285 -- State >= Done, in which case it may or may not be still Onqueue.
287 -- Please do not modify the order of the values, without checking
288 -- all uses of this type. We rely on partial "monotonicity" of
289 -- Entry_Call_Record.State to avoid locking when we access this
290 -- value for certain tests. In particular:
292 -- 1) Once State >= Done, we can rely that the call has been
293 -- completed. If State >= Done, it will not
294 -- change until the task does another entry call at this level.
296 -- 2) Once State >= Was_Abortable, we can rely that the call has
297 -- been queued abortably at least once, and so the check for
298 -- whether it is OK to advance to the abortable part of an
299 -- async. select statement does not need to lock anything.
301 type Restricted_Entry_Call_Record is record
307 State : Entry_Call_State;
308 pragma Atomic (State);
309 -- Indicates part of the state of the call.
311 -- Protection: If the call is not on a queue, it should only be
312 -- accessed by Self, and Self does not need any lock to modify this
315 -- Once the call is on a queue, the value should be something other
316 -- than Done unless it is cancelled, and access is controller by the
317 -- "server" of the queue -- i.e., the lock of Checked_To_Protection
318 -- (Call_Target) if the call record is on the queue of a PO, or the
319 -- lock of Called_Target if the call is on the queue of a task. See
320 -- comments on type declaration for more details.
322 Uninterpreted_Data : System.Address;
323 -- Data passed by the compiler
325 Exception_To_Raise : Ada.Exceptions.Exception_Id;
326 -- The exception to raise once this call has been completed without
329 pragma Suppress_Initialization (Restricted_Entry_Call_Record);
331 ------------------------------------
332 -- Task related other definitions --
333 ------------------------------------
335 type Activation_Chain is limited private;
336 -- Comment required ???
338 type Activation_Chain_Access is access all Activation_Chain;
339 -- Comment required ???
341 type Task_Procedure_Access is access procedure (Arg : System.Address);
343 type Access_Boolean is access all Boolean;
345 Detect_Blocking : constant Boolean;
346 -- Boolean constant set True iff Detect_Blocking is active
348 ----------------------------------------------
349 -- Ada_Task_Control_Block (ATCB) definition --
350 ----------------------------------------------
352 -- Notes on protection (synchronization) of TRTS data structures
354 -- Any field of the TCB can be written by the activator of a task when the
355 -- task is created, since no other task can access the new task's
356 -- state until creation is complete.
358 -- The protection for each field is described in a comment starting with
361 -- When a lock is used to protect an ATCB field, this lock is simply named
363 -- Some protection is described in terms of tasks related to the
364 -- ATCB being protected. These are:
366 -- Self: The task which is controlled by this ATCB
367 -- Acceptor: A task accepting a call from Self
368 -- Caller: A task calling an entry of Self
369 -- Parent: The task executing the master on which Self depends
370 -- Dependent: A task dependent on Self
371 -- Activator: The task that created Self and initiated its activation
372 -- Created: A task created and activated by Self
374 -- Note: The order of the fields is important to implement efficiently
375 -- tasking support under gdb.
376 -- Currently gdb relies on the order of the State, Parent, Base_Priority,
377 -- Task_Image, Task_Image_Len, Call and LL fields.
379 -------------------------
380 -- Common ATCB section --
381 -------------------------
383 -- Section used by all GNARL implementations (regular and restricted)
385 type Common_ATCB is record
387 pragma Atomic (State);
388 -- Encodes some basic information about the state of a task,
389 -- including whether it has been activated, whether it is sleeping,
390 -- and whether it is terminated.
392 -- Protection: Self.L
395 -- The task on which this task depends.
396 -- See also Master_Level and Master_Within.
398 Base_Priority : System.Any_Priority;
399 -- Base priority, not changed during entry calls, only changed
400 -- via dynamic priorities package.
402 -- Protection: Only written by Self, accessed by anyone
404 Current_Priority : System.Any_Priority;
405 -- Active priority, except that the effects of protected object
406 -- priority ceilings are not reflected. This only reflects explicit
407 -- priority changes and priority inherited through task activation
410 -- Ada 95 notes: In Ada 95, this field will be transferred to the
411 -- Priority field of an Entry_Calls component when an entry call
412 -- is initiated. The Priority of the Entry_Calls component will not
413 -- change for the duration of the call. The accepting task can
414 -- use it to boost its own priority without fear of its changing in
417 -- This can safely be used in the priority ordering
418 -- of entry queues. Once a call is queued, its priority does not
421 -- Since an entry call cannot be made while executing
422 -- a protected action, the priority of a task will never reflect a
423 -- priority ceiling change at the point of an entry call.
425 -- Protection: Only written by Self, and only accessed when Acceptor
426 -- accepts an entry or when Created activates, at which points Self is
429 Protected_Action_Nesting : Natural;
430 pragma Atomic (Protected_Action_Nesting);
431 -- The dynamic level of protected action nesting for this task. This
432 -- field is needed for checking whether potentially blocking operations
433 -- are invoked from protected actions. pragma Atomic is used because it
434 -- can be read/written from protected interrupt handlers.
436 Task_Image : String (1 .. 32);
437 -- Hold a string that provides a readable id for task,
438 -- built from the variable of which it is a value or component.
440 Task_Image_Len : Natural;
441 -- Actual length of Task_Image
443 Call : Entry_Call_Link;
444 -- The entry call that has been accepted by this task.
446 -- Protection: Self.L. Self will modify this field when Self.Accepting
447 -- is False, and will not need the mutex to do so. Once a task sets
448 -- Pending_ATC_Level = 0, no other task can access this field.
450 LL : aliased Task_Primitives.Private_Data;
451 -- Control block used by the underlying low-level tasking service
454 -- Protection: This is used only by the GNULLI implementation, which
455 -- takes care of all of its synchronization.
457 Task_Arg : System.Address;
458 -- The argument to task procedure. Provide a handle for discriminant
461 -- Protection: Part of the synchronization between Self and Activator.
462 -- Activator writes it, once, before Self starts executing. Thereafter,
463 -- Self only reads it.
465 Task_Entry_Point : Task_Procedure_Access;
466 -- Information needed to call the procedure containing the code for
467 -- the body of this task.
469 -- Protection: Part of the synchronization between Self and Activator.
470 -- Activator writes it, once, before Self starts executing. Self reads
471 -- it, once, as part of its execution.
473 Compiler_Data : System.Soft_Links.TSD;
474 -- Task-specific data needed by the compiler to store per-task
477 -- Protection: Only accessed by Self
479 All_Tasks_Link : Task_Id;
480 -- Used to link this task to the list of all tasks in the system
482 -- Protection: RTS_Lock
484 Activation_Link : Task_Id;
485 -- Used to link this task to a list of tasks to be activated
487 -- Protection: Only used by Activator
490 -- The task that created this task, either by declaring it as a task
491 -- object or by executing a task allocator. The value is null iff Self
492 -- has completed activation.
494 -- Protection: Set by Activator before Self is activated, and only read
495 -- and modified by Self after that.
497 Wait_Count : Integer;
498 -- This count is used by a task that is waiting for other tasks. At all
499 -- other times, the value should be zero. It is used differently in
500 -- several different states. Since a task cannot be in more than one of
501 -- these states at the same time, a single counter suffices.
503 -- Protection: Self.L
507 -- This is the number of tasks that this task is activating, i.e. the
508 -- children that have started activation but have not completed it.
510 -- Protection: Self.L and Created.L. Both mutexes must be locked, since
511 -- Self.Activation_Count and Created.State must be synchronized.
513 -- Master_Completion_Sleep (phase 1)
515 -- This is the number dependent tasks of a master being completed by
516 -- Self that are not activated, not terminated, and not waiting on a
517 -- terminate alternative.
519 -- Master_Completion_2_Sleep (phase 2)
521 -- This is the count of tasks dependent on a master being completed by
522 -- Self which are waiting on a terminate alternative.
524 Elaborated : Access_Boolean;
525 -- Pointer to a flag indicating that this task's body has been
526 -- elaborated. The flag is created and managed by the
527 -- compiler-generated code.
529 -- Protection: The field itself is only accessed by Activator. The flag
530 -- that it points to is updated by Master and read by Activator; access
531 -- is assumed to be atomic.
533 Activation_Failed : Boolean;
534 -- Set to True if activation of a chain of tasks fails,
535 -- so that the activator should raise Tasking_Error.
537 Task_Info : System.Task_Info.Task_Info_Type;
538 -- System-specific attributes of the task as specified by the
542 ---------------------------------------
543 -- Restricted_Ada_Task_Control_Block --
544 ---------------------------------------
546 -- This type should only be used by the restricted GNARLI and by
547 -- restricted GNULL implementations to allocate an ATCB (see
548 -- System.Task_Primitives.Operations.New_ATCB) that will take
549 -- significantly less memory.
551 -- Note that the restricted GNARLI should only access fields that are
552 -- present in the Restricted_Ada_Task_Control_Block structure.
554 type Restricted_Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is
556 Common : Common_ATCB;
557 -- The common part between various tasking implementations
559 Entry_Call : aliased Restricted_Entry_Call_Record;
560 -- Protection: This field is used on entry call "queues" associated
561 -- with protected objects, and is protected by the protected object
564 pragma Suppress_Initialization (Restricted_Ada_Task_Control_Block);
566 Interrupt_Manager_ID : Task_Id;
567 -- This task ID is declared here to break circular dependencies.
568 -- Also declare Interrupt_Manager_ID after Task_Id is known, to avoid
569 -- generating unneeded finalization code.
571 -----------------------
572 -- List of all Tasks --
573 -----------------------
575 All_Tasks_List : Task_Id;
576 -- Global linked list of all tasks
578 ------------------------------------------
579 -- Regular (non restricted) definitions --
580 ------------------------------------------
582 --------------------------------
583 -- Master Related Definitions --
584 --------------------------------
586 subtype Master_Level is Integer;
587 subtype Master_ID is Master_Level;
589 -- Normally, a task starts out with internal master nesting level one
590 -- larger than external master nesting level. It is incremented to one by
591 -- Enter_Master, which is called in the task body only if the compiler
592 -- thinks the task may have dependent tasks. It is set to for the
593 -- environment task, the level 2 is reserved for server tasks of the
594 -- run-time system (the so called "independent tasks"), and the level 3 is
595 -- for the library level tasks.
597 Environment_Task_Level : constant Master_Level := 1;
598 Independent_Task_Level : constant Master_Level := 2;
599 Library_Task_Level : constant Master_Level := 3;
601 ------------------------------
602 -- Task size, priority info --
603 ------------------------------
605 Unspecified_Priority : constant Integer := System.Priority'First - 1;
607 Priority_Not_Boosted : constant Integer := System.Priority'First - 1;
608 -- Definition of Priority actually has to come from the RTS configuration
610 subtype Rendezvous_Priority is Integer
611 range Priority_Not_Boosted .. System.Any_Priority'Last;
613 ------------------------------------
614 -- Rendezvous related definitions --
615 ------------------------------------
617 No_Rendezvous : constant := 0;
619 Max_Select : constant Integer := Integer'Last;
622 subtype Select_Index is Integer range No_Rendezvous .. Max_Select;
623 -- type Select_Index is range No_Rendezvous .. Max_Select;
625 subtype Positive_Select_Index is
626 Select_Index range 1 .. Select_Index'Last;
628 type Accept_Alternative is record
630 S : Task_Entry_Index;
634 array (Positive_Select_Index range <>) of Accept_Alternative;
636 type Accept_List_Access is access constant Accept_List;
638 -----------------------------------
639 -- ATC_Level related definitions --
640 -----------------------------------
642 Max_ATC_Nesting : constant Natural := 20;
644 subtype ATC_Level_Base is Integer range 0 .. Max_ATC_Nesting;
646 ATC_Level_Infinity : constant ATC_Level_Base := ATC_Level_Base'Last;
648 subtype ATC_Level is ATC_Level_Base range 0 .. ATC_Level_Base'Last - 1;
650 subtype ATC_Level_Index is ATC_Level range 1 .. ATC_Level'Last;
652 ----------------------------------
653 -- Entry_Call_Record definition --
654 ----------------------------------
656 type Entry_Call_Record is record
662 State : Entry_Call_State;
663 pragma Atomic (State);
664 -- Indicates part of the state of the call
666 -- Protection: If the call is not on a queue, it should only be
667 -- accessed by Self, and Self does not need any lock to modify this
668 -- field. Once the call is on a queue, the value should be something
669 -- other than Done unless it is cancelled, and access is controller by
670 -- the "server" of the queue -- i.e., the lock of Checked_To_Protection
671 -- (Call_Target) if the call record is on the queue of a PO, or the
672 -- lock of Called_Target if the call is on the queue of a task. See
673 -- comments on type declaration for more details.
675 Uninterpreted_Data : System.Address;
676 -- Data passed by the compiler
678 Exception_To_Raise : Ada.Exceptions.Exception_Id;
679 -- The exception to raise once this call has been completed without
682 Prev : Entry_Call_Link;
684 Next : Entry_Call_Link;
687 -- One of Self and Level are redundant in this implementation, since
688 -- each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must
689 -- have access to the entry call record to be reading this, we could
690 -- get Self from Level, or Level from Self. However, this requires
691 -- non-portable address arithmetic.
695 Prio : System.Any_Priority;
697 -- The above fields are those that there may be some hope of packing.
698 -- They are gathered together to allow for compilers that lay records
699 -- out contiguously, to allow for such packing.
701 Called_Task : Task_Id;
702 pragma Atomic (Called_Task);
703 -- Use for task entry calls. The value is null if the call record is
704 -- not in use. Conversely, unless State is Done and Onqueue is false,
705 -- Called_Task points to an ATCB.
707 -- Protection: Called_Task.L
709 Called_PO : System.Address;
710 pragma Atomic (Called_PO);
711 -- Similar to Called_Task but for protected objects
713 -- Note that the previous implementation tried to merge both
714 -- Called_Task and Called_PO but this ended up in many unexpected
715 -- complications (e.g having to add a magic number in the ATCB, which
716 -- caused gdb lots of confusion) with no real gain since the
717 -- Lock_Server implementation still need to loop around chasing for
718 -- pointer changes even with a single pointer.
720 Acceptor_Prev_Call : Entry_Call_Link;
721 -- For task entry calls only
723 Acceptor_Prev_Priority : Rendezvous_Priority := Priority_Not_Boosted;
724 -- For task entry calls only. The priority of the most recent prior
725 -- call being serviced. For protected entry calls, this function should
726 -- be performed by GNULLI ceiling locking.
728 Cancellation_Attempted : Boolean := False;
729 pragma Atomic (Cancellation_Attempted);
730 -- Cancellation of the call has been attempted.
731 -- Consider merging this into State???
733 Requeue_With_Abort : Boolean := False;
734 -- Temporary to tell caller whether requeue is with abort.
735 -- Find a better way of doing this ???
737 Needs_Requeue : Boolean := False;
738 -- Temporary to tell acceptor of task entry call that
739 -- Exceptional_Complete_Rendezvous needs to do requeue.
742 ------------------------------------
743 -- Task related other definitions --
744 ------------------------------------
746 type Access_Address is access all System.Address;
747 -- Comment on what this is used for ???
749 pragma No_Strict_Aliasing (Access_Address);
750 -- This type is used in contexts where aliasing may be an issue (see
751 -- for example s-tataat.adb), so we avoid any incorrect aliasing
754 ----------------------------------------------
755 -- Ada_Task_Control_Block (ATCB) definition --
756 ----------------------------------------------
758 type Entry_Call_Array is array (ATC_Level_Index) of
759 aliased Entry_Call_Record;
761 type Direct_Index is range 0 .. Parameters.Default_Attribute_Count;
762 subtype Direct_Index_Range is Direct_Index range 1 .. Direct_Index'Last;
763 -- Attributes with indices in this range are stored directly in the task
764 -- control block. Such attributes must be Address-sized. Other attributes
765 -- will be held in dynamically allocated records chained off of the task
768 type Direct_Attribute_Element is mod Memory_Size;
769 pragma Atomic (Direct_Attribute_Element);
771 type Direct_Attribute_Array is
772 array (Direct_Index_Range) of aliased Direct_Attribute_Element;
774 type Direct_Index_Vector is mod 2 ** Parameters.Default_Attribute_Count;
775 -- This is a bit-vector type, used to store information about
776 -- the usage of the direct attribute fields.
778 type Task_Serial_Number is mod 2 ** 64;
779 -- Used to give each task a unique serial number
781 type Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is record
782 Common : Common_ATCB;
783 -- The common part between various tasking implementations
785 Entry_Calls : Entry_Call_Array;
786 -- An array of entry calls
788 -- Protection: The elements of this array are on entry call queues
789 -- associated with protected objects or task entries, and are protected
790 -- by the protected object lock or Acceptor.L, respectively.
792 New_Base_Priority : System.Any_Priority;
793 -- New value for Base_Priority (for dynamic priorities package)
795 -- Protection: Self.L
797 Global_Task_Lock_Nesting : Natural := 0;
798 -- This is the current nesting level of calls to
799 -- System.Tasking.Stages.Lock_Task_T. This allows a task to call
800 -- Lock_Task_T multiple times without deadlocking. A task only locks
801 -- All_Task_Lock when its All_Tasks_Nesting goes from 0 to 1, and only
802 -- unlocked when it goes from 1 to 0.
804 -- Protection: Only accessed by Self
806 Open_Accepts : Accept_List_Access;
807 -- This points to the Open_Accepts array of accept alternatives passed
808 -- to the RTS by the compiler-generated code to Selective_Wait. It is
809 -- non-null iff this task is ready to accept an entry call.
811 -- Protection: Self.L
813 Chosen_Index : Select_Index;
814 -- The index in Open_Accepts of the entry call accepted by a selective
815 -- wait executed by this task.
817 -- Protection: Written by both Self and Caller. Usually protected by
818 -- Self.L. However, once the selection is known to have been written it
819 -- can be accessed without protection. This happens after Self has
820 -- updated it itself using information from a suspended Caller, or
821 -- after Caller has updated it and awakened Self.
823 Master_of_Task : Master_Level;
824 -- The task executing the master of this task, and the ID of this task's
825 -- master (unique only among masters currently active within Parent).
827 -- Protection: Set by Activator before Self is activated, and read
828 -- after Self is activated.
830 Master_Within : Master_Level;
831 -- The ID of the master currently executing within this task; that is,
832 -- the most deeply nested currently active master.
834 -- Protection: Only written by Self, and only read by Self or by
835 -- dependents when Self is attempting to exit a master. Since Self will
836 -- not write this field until the master is complete, the
837 -- synchronization should be adequate to prevent races.
839 Alive_Count : Integer := 0;
840 -- Number of tasks directly dependent on this task (including itself)
841 -- that are still "alive", i.e. not terminated.
843 -- Protection: Self.L
845 Awake_Count : Integer := 0;
846 -- Number of tasks directly dependent on this task (including itself)
847 -- still "awake", i.e., are not terminated and not waiting on a
848 -- terminate alternative.
850 -- Invariant: Awake_Count <= Alive_Count
852 -- Protection: Self.L
854 -- Beginning of flags
856 Aborting : Boolean := False;
857 pragma Atomic (Aborting);
858 -- Self is in the process of aborting. While set, prevents multiple
859 -- abort signals from being sent by different aborter while abort
860 -- is acted upon. This is essential since an aborter which calls
861 -- Abort_To_Level could set the Pending_ATC_Level to yet a lower level
862 -- (than the current level), may be preempted and would send the
863 -- abort signal when resuming execution. At this point, the abortee
864 -- may have completed abort to the proper level such that the
865 -- signal (and resulting abort exception) are not handled any more.
866 -- In other words, the flag prevents a race between multiple aborters
868 -- Protection: protected by atomic access.
870 ATC_Hack : Boolean := False;
871 pragma Atomic (ATC_Hack);
873 -- Temporary fix, to allow Undefer_Abort to reset Aborting in the
874 -- handler for Abort_Signal that encloses an async. entry call.
875 -- For the longer term, this should be done via code in the
878 Callable : Boolean := True;
879 -- It is OK to call entries of this task
881 Dependents_Aborted : Boolean := False;
882 -- This is set to True by whichever task takes responsibility for
883 -- aborting the dependents of this task.
885 -- Protection: Self.L
887 Interrupt_Entry : Boolean := False;
888 -- Indicates if one or more Interrupt Entries are attached to the task.
889 -- This flag is needed for cleaning up the Interrupt Entry bindings.
891 Pending_Action : Boolean := False;
892 -- Unified flag indicating some action needs to be take when abort
893 -- next becomes undeferred. Currently set if:
894 -- . Pending_Priority_Change is set
895 -- . Pending_ATC_Level is changed
896 -- . Requeue involving POs
897 -- (Abortable field may have changed and the Wait_Until_Abortable
898 -- has to recheck the abortable status of the call.)
899 -- . Exception_To_Raise is non-null
901 -- Protection: Self.L
903 -- This should never be reset back to False outside of the procedure
904 -- Do_Pending_Action, which is called by Undefer_Abort. It should only
905 -- be set to True by Set_Priority and Abort_To_Level.
907 Pending_Priority_Change : Boolean := False;
908 -- Flag to indicate pending priority change (for dynamic priorities
909 -- package). The base priority is updated on the next abort
910 -- completion point (aka. synchronization point).
912 -- Protection: Self.L
914 Terminate_Alternative : Boolean := False;
915 -- Task is accepting Select with Terminate Alternative
917 -- Protection: Self.L
921 -- Beginning of counts
923 ATC_Nesting_Level : ATC_Level := 1;
924 -- The dynamic level of ATC nesting (currently executing nested
925 -- asynchronous select statements) in this task.
927 -- Protection: Self_ID.L. Only Self reads or updates this field.
928 -- Decrementing it deallocates an Entry_Calls component, and care must
929 -- be taken that all references to that component are eliminated before
930 -- doing the decrement. This in turn will require locking a protected
931 -- object (for a protected entry call) or the Acceptor's lock (for a
932 -- task entry call). No other task should attempt to read or modify
935 Deferral_Level : Natural := 1;
936 -- This is the number of times that Defer_Abortion has been called by
937 -- this task without a matching Undefer_Abortion call. Abortion is only
938 -- allowed when this zero. It is initially 1, to protect the task at
941 -- Protection: Only updated by Self; access assumed to be atomic
943 Pending_ATC_Level : ATC_Level_Base := ATC_Level_Infinity;
944 -- The ATC level to which this task is currently being aborted. If the
945 -- value is zero, the entire task has "completed". That may be via
946 -- abort, exception propagation, or normal exit. If the value is
947 -- ATC_Level_Infinity, the task is not being aborted to any level. If
948 -- the value is positive, the task has not completed. This should ONLY
949 -- be modified by Abort_To_Level and Exit_One_ATC_Level.
951 -- Protection: Self.L
953 Serial_Number : Task_Serial_Number;
954 -- A growing number to provide some way to check locking rules/ordering
956 Known_Tasks_Index : Integer := -1;
957 -- Index in the System.Tasking.Debug.Known_Tasks array
959 User_State : Long_Integer := 0;
960 -- User-writeable location, for use in debugging tasks; also provides a
961 -- simple task specific data.
963 Direct_Attributes : Direct_Attribute_Array;
964 -- For task attributes that have same size as Address
966 Is_Defined : Direct_Index_Vector := 0;
967 -- Bit I is 1 iff Direct_Attributes (I) is defined
969 Indirect_Attributes : Access_Address;
970 -- A pointer to chain of records for other attributes that are not
971 -- address-sized, including all tagged types.
973 Entry_Queues : Task_Entry_Queue_Array (1 .. Entry_Num);
974 -- An array of task entry queues
976 -- Protection: Self.L. Once a task has set Self.Stage to Completing, it
977 -- has exclusive access to this field.
980 ---------------------
981 -- Initialize_ATCB --
982 ---------------------
984 procedure Initialize_ATCB
986 Task_Entry_Point : Task_Procedure_Access;
987 Task_Arg : System.Address;
989 Elaborated : Access_Boolean;
990 Base_Priority : System.Any_Priority;
991 Task_Info : System.Task_Info.Task_Info_Type;
992 Stack_Size : System.Parameters.Size_Type;
994 Success : out Boolean);
995 -- Initialize fields of a TCB and link into global TCB structures Call
996 -- this only with abort deferred and holding RTS_Lock. Need more
997 -- documentation, mention T, and describe Success ???
1000 Null_Task : constant Task_Id := null;
1002 GL_Detect_Blocking : Integer;
1003 pragma Import (C, GL_Detect_Blocking, "__gl_detect_blocking");
1004 -- Global variable exported by the binder generated file. A value equal to
1005 -- 1 indicates that pragma Detect_Blocking is active, while 0 is used for
1006 -- the pragma not being present.
1008 Detect_Blocking : constant Boolean := GL_Detect_Blocking = 1;
1010 type Activation_Chain is record
1013 pragma Volatile (Activation_Chain);
1015 -- Activation_chain is an in-out parameter of initialization procedures
1016 -- and it must be passed by reference because the init proc may terminate
1017 -- abnormally after creating task components, and these must be properly
1018 -- registered for removal (Expunge_Unactivated_Tasks).