1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- S Y S T E M . T A S K I N G --
9 -- Copyright (C) 1992-2008, 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, 51 Franklin Street, Fifth Floor, --
20 -- Boston, MA 02110-1301, 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 with Ada.Unchecked_Conversion;
42 with System.Parameters;
43 with System.Task_Info;
44 with System.Soft_Links;
45 with System.Task_Primitives;
46 with System.Stack_Usage;
48 package System.Tasking is
55 -- The following rules must be followed at all times, to prevent
56 -- deadlock and generally ensure correct operation of locking.
58 -- Never lock a lock unless abort is deferred
60 -- Never undefer abort while holding a lock
62 -- Overlapping critical sections must be properly nested, and locks must
63 -- be released in LIFO order. E.g., the following is not allowed:
73 -- Locks with lower (smaller) level number cannot be locked
74 -- while holding a lock with a higher level number. (The level
76 -- 1. System.Tasking.PO_Simple.Protection.L (any PO lock)
77 -- 2. System.Tasking.Initialization.Global_Task_Lock (in body)
78 -- 3. System.Task_Primitives.Operations.Single_RTS_Lock
79 -- 4. System.Tasking.Ada_Task_Control_Block.LL.L (any TCB lock)
81 -- Clearly, there can be no circular chain of hold-and-wait
82 -- relationships involving locks in different ordering levels.
84 -- We used to have Global_Task_Lock before Protection.L but this was
85 -- clearly wrong since there can be calls to "new" inside protected
86 -- operations. The new ordering prevents these failures.
88 -- Sometimes we need to hold two ATCB locks at the same time. To allow us
89 -- to order the locking, each ATCB is given a unique serial number. If one
90 -- needs to hold locks on several ATCBs at once, the locks with lower
91 -- serial numbers must be locked first.
93 -- We don't always need to check the serial numbers, since the serial
94 -- numbers are assigned sequentially, and so:
96 -- . The parent of a task always has a lower serial number.
97 -- . The activator of a task always has a lower serial number.
98 -- . The environment task has a lower serial number than any other task.
99 -- . If the activator of a task is different from the task's parent,
100 -- the parent always has a lower serial number than the activator.
102 ---------------------------------
103 -- Task_Id related definitions --
104 ---------------------------------
106 type Ada_Task_Control_Block;
108 type Task_Id is access all Ada_Task_Control_Block;
109 for Task_Id'Size use System.Task_Primitives.Task_Address_Size;
111 Null_Task : constant Task_Id;
113 type Task_List is array (Positive range <>) of Task_Id;
115 function Self return Task_Id;
116 pragma Inline (Self);
117 -- This is the compiler interface version of this function. Do not call
118 -- from the run-time system.
120 function To_Task_Id is
121 new Ada.Unchecked_Conversion
122 (System.Task_Primitives.Task_Address, Task_Id);
123 function To_Address is
124 new Ada.Unchecked_Conversion
125 (Task_Id, System.Task_Primitives.Task_Address);
127 -----------------------
128 -- Enumeration types --
129 -----------------------
133 -- Task has been created but has not been activated.
134 -- It cannot be executing.
137 -- For all states from here down, the task has been activated.
138 -- For all states from here down, except for Terminated, the task
140 -- Activator = null iff it has not yet completed activating.
142 -- For all states from here down,
143 -- the task has been activated, and may be executing.
146 -- Task is not blocked for any reason known to Ada.
147 -- (It may be waiting for a mutex, though.)
148 -- It is conceptually "executing" in normal mode.
151 -- The task is terminated, in the sense of ARM 9.3 (5).
152 -- Any dependents that were waiting on terminate
153 -- alternatives have been awakened and have terminated themselves.
156 -- Task is waiting for created tasks to complete activation
159 -- Task is waiting on an accept or selective wait statement
162 -- Task is waiting on an entry call
165 -- Task is waiting to start the abortable part of an
166 -- asynchronous select statement.
169 -- Task is waiting on a select statement with only a delay
172 Master_Completion_Sleep,
173 -- Master completion has two phases.
174 -- In Phase 1 the task is sleeping in Complete_Master
175 -- having completed a master within itself,
176 -- and is waiting for the tasks dependent on that master to become
177 -- terminated or waiting on a terminate Phase.
179 Master_Phase_2_Sleep,
180 -- In Phase 2 the task is sleeping in Complete_Master
181 -- waiting for tasks on terminate alternatives to finish
184 -- The following are special uses of sleep, for server tasks
185 -- within the run-time system.
187 Interrupt_Server_Idle_Sleep,
188 Interrupt_Server_Blocked_Interrupt_Sleep,
193 -- The task has been held by Asynchronous_Task_Control.Hold_Task
195 Interrupt_Server_Blocked_On_Event_Flag
196 -- The task has been blocked on a system call waiting for a
197 -- completion event/signal to occur.
201 (Simple_Call, Conditional_Call, Asynchronous_Call, Timed_Call);
203 type Select_Modes is (Simple_Mode, Else_Mode, Terminate_Mode, Delay_Mode);
205 subtype Delay_Modes is Integer;
207 -------------------------------
208 -- Entry related definitions --
209 -------------------------------
211 Null_Entry : constant := 0;
213 Max_Entry : constant := Integer'Last;
215 Interrupt_Entry : constant := -2;
217 Cancelled_Entry : constant := -1;
219 type Entry_Index is range Interrupt_Entry .. Max_Entry;
221 Null_Task_Entry : constant := Null_Entry;
223 Max_Task_Entry : constant := Max_Entry;
225 type Task_Entry_Index is new Entry_Index
226 range Null_Task_Entry .. Max_Task_Entry;
228 type Entry_Call_Record;
230 type Entry_Call_Link is access all Entry_Call_Record;
232 type Entry_Queue is record
233 Head : Entry_Call_Link;
234 Tail : Entry_Call_Link;
237 type Task_Entry_Queue_Array is
238 array (Task_Entry_Index range <>) of Entry_Queue;
240 -- A data structure which contains the string names of entries and entry
243 type String_Access is access all String;
245 type Entry_Names_Array is
246 array (Entry_Index range <>) of String_Access;
248 type Entry_Names_Array_Access is access all Entry_Names_Array;
250 procedure Free_Entry_Names_Array (Obj : in out Entry_Names_Array);
251 -- Deallocate all string names contained in an entry names array
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 -- Protection: If the call is not on a queue, it should only be
323 -- accessed by Self, and Self does not need any lock to modify this
326 -- Once the call is on a queue, the value should be something other
327 -- than Done unless it is cancelled, and access is controller by the
328 -- "server" of the queue -- i.e., the lock of Checked_To_Protection
329 -- (Call_Target) if the call record is on the queue of a PO, or the
330 -- lock of Called_Target if the call is on the queue of a task. See
331 -- 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 termination procedure definition --
344 -------------------------------------------
346 -- We need to redefine here these types (already defined in
347 -- Ada.Task_Termination) for avoiding circular dependencies.
349 type Cause_Of_Termination is (Normal, Abnormal, Unhandled_Exception);
350 -- Possible causes for task termination:
352 -- Normal means that the task terminates due to completing the
353 -- last sentence of its body, or as a result of waiting on a
354 -- terminate alternative.
356 -- Abnormal means that the task terminates because it is being aborted
358 -- handled_Exception means that the task terminates because of exception
359 -- raised by the execution of its task_body.
361 type Termination_Handler is access protected procedure
362 (Cause : Cause_Of_Termination;
364 X : Ada.Exceptions.Exception_Occurrence);
365 -- Used to represent protected procedures to be executed when task
368 ------------------------------------
369 -- Task related other definitions --
370 ------------------------------------
372 type Activation_Chain is limited private;
373 -- Linked list of to-be-activated tasks, linked through
374 -- Activation_Link. The order of tasks on the list is irrelevant, because
375 -- the priority rules will ensure that they actually start activating in
378 type Activation_Chain_Access is access all Activation_Chain;
380 type Task_Procedure_Access is access procedure (Arg : System.Address);
382 type Access_Boolean is access all Boolean;
384 function Detect_Blocking return Boolean;
385 pragma Inline (Detect_Blocking);
386 -- Return whether the Detect_Blocking pragma is enabled
388 function Storage_Size (T : Task_Id) return System.Parameters.Size_Type;
389 -- Retrieve from the TCB of the task the allocated size of its stack,
390 -- either the system default or the size specified by a pragma. This
391 -- is in general a non-static value that can depend on discriminants
394 ----------------------------------------------
395 -- Ada_Task_Control_Block (ATCB) definition --
396 ----------------------------------------------
398 -- Notes on protection (synchronization) of TRTS data structures
400 -- Any field of the TCB can be written by the activator of a task when the
401 -- task is created, since no other task can access the new task's
402 -- state until creation is complete.
404 -- The protection for each field is described in a comment starting with
407 -- When a lock is used to protect an ATCB field, this lock is simply named
409 -- Some protection is described in terms of tasks related to the
410 -- ATCB being protected. These are:
412 -- Self: The task which is controlled by this ATCB
413 -- Acceptor: A task accepting a call from Self
414 -- Caller: A task calling an entry of Self
415 -- Parent: The task executing the master on which Self depends
416 -- Dependent: A task dependent on Self
417 -- Activator: The task that created Self and initiated its activation
418 -- Created: A task created and activated by Self
420 -- Note: The order of the fields is important to implement efficiently
421 -- tasking support under gdb.
422 -- Currently gdb relies on the order of the State, Parent, Base_Priority,
423 -- Task_Image, Task_Image_Len, Call and LL fields.
425 -------------------------
426 -- Common ATCB section --
427 -------------------------
429 -- Section used by all GNARL implementations (regular and restricted)
431 type Common_ATCB is record
433 pragma Atomic (State);
434 -- Encodes some basic information about the state of a task,
435 -- including whether it has been activated, whether it is sleeping,
436 -- and whether it is terminated.
438 -- Protection: Self.L
441 -- The task on which this task depends.
442 -- See also Master_Level and Master_Within.
444 Base_Priority : System.Any_Priority;
445 -- Base priority, not changed during entry calls, only changed
446 -- via dynamic priorities package.
448 -- Protection: Only written by Self, accessed by anyone
450 Current_Priority : System.Any_Priority;
451 -- Active priority, except that the effects of protected object
452 -- priority ceilings are not reflected. This only reflects explicit
453 -- priority changes and priority inherited through task activation
456 -- Ada 95 notes: In Ada 95, this field will be transferred to the
457 -- Priority field of an Entry_Calls component when an entry call is
458 -- initiated. The Priority of the Entry_Calls component will not change
459 -- for the duration of the call. The accepting task can use it to boost
460 -- its own priority without fear of its changing in the meantime.
462 -- This can safely be used in the priority ordering of entry queues.
463 -- Once a call is queued, its priority does not change.
465 -- Since an entry call cannot be made while executing a protected
466 -- action, the priority of a task will never reflect a priority ceiling
467 -- change at the point of an entry call.
469 -- Protection: Only written by Self, and only accessed when Acceptor
470 -- accepts an entry or when Created activates, at which points Self is
473 Protected_Action_Nesting : Natural;
474 pragma Atomic (Protected_Action_Nesting);
475 -- The dynamic level of protected action nesting for this task. This
476 -- field is needed for checking whether potentially blocking operations
477 -- are invoked from protected actions. pragma Atomic is used because it
478 -- can be read/written from protected interrupt handlers.
480 Task_Image : String (1 .. System.Parameters.Max_Task_Image_Length);
481 -- Hold a string that provides a readable id for task, built from the
482 -- variable of which it is a value or component.
484 Task_Image_Len : Natural;
485 -- Actual length of Task_Image
487 Call : Entry_Call_Link;
488 -- The entry call that has been accepted by this task.
490 -- Protection: Self.L. Self will modify this field when Self.Accepting
491 -- is False, and will not need the mutex to do so. Once a task sets
492 -- Pending_ATC_Level = 0, no other task can access this field.
494 LL : aliased Task_Primitives.Private_Data;
495 -- Control block used by the underlying low-level tasking service
498 -- Protection: This is used only by the GNULLI implementation, which
499 -- takes care of all of its synchronization.
501 Task_Arg : System.Address;
502 -- The argument to task procedure. Provide a handle for discriminant
505 -- Protection: Part of the synchronization between Self and Activator.
506 -- Activator writes it, once, before Self starts executing. Thereafter,
507 -- Self only reads it.
509 Task_Alternate_Stack : System.Address;
510 -- The address of the alternate signal stack for this task, if any
512 -- Protection: Only accessed by Self
514 Task_Entry_Point : Task_Procedure_Access;
515 -- Information needed to call the procedure containing the code for
516 -- the body of this task.
518 -- Protection: Part of the synchronization between Self and Activator.
519 -- Activator writes it, once, before Self starts executing. Self reads
520 -- it, once, as part of its execution.
522 Compiler_Data : System.Soft_Links.TSD;
523 -- Task-specific data needed by the compiler to store per-task
526 -- Protection: Only accessed by Self
528 All_Tasks_Link : Task_Id;
529 -- Used to link this task to the list of all tasks in the system
531 -- Protection: RTS_Lock
533 Activation_Link : Task_Id;
534 -- Used to link this task to a list of tasks to be activated
536 -- Protection: Only used by Activator
539 -- The task that created this task, either by declaring it as a task
540 -- object or by executing a task allocator. The value is null iff Self
541 -- has completed activation.
543 -- Protection: Set by Activator before Self is activated, and only read
544 -- and modified by Self after that.
546 Wait_Count : Integer;
547 -- This count is used by a task that is waiting for other tasks. At all
548 -- other times, the value should be zero. It is used differently in
549 -- several different states. Since a task cannot be in more than one of
550 -- these states at the same time, a single counter suffices.
552 -- Protection: Self.L
556 -- This is the number of tasks that this task is activating, i.e. the
557 -- children that have started activation but have not completed it.
559 -- Protection: Self.L and Created.L. Both mutexes must be locked, since
560 -- Self.Activation_Count and Created.State must be synchronized.
562 -- Master_Completion_Sleep (phase 1)
564 -- This is the number dependent tasks of a master being completed by
565 -- Self that are not activated, not terminated, and not waiting on a
566 -- terminate alternative.
568 -- Master_Completion_2_Sleep (phase 2)
570 -- This is the count of tasks dependent on a master being completed by
571 -- Self which are waiting on a terminate alternative.
573 Elaborated : Access_Boolean;
574 -- Pointer to a flag indicating that this task's body has been
575 -- elaborated. The flag is created and managed by the
576 -- compiler-generated code.
578 -- Protection: The field itself is only accessed by Activator. The flag
579 -- that it points to is updated by Master and read by Activator; access
580 -- is assumed to be atomic.
582 Activation_Failed : Boolean;
583 -- Set to True if activation of a chain of tasks fails,
584 -- so that the activator should raise Tasking_Error.
586 Task_Info : System.Task_Info.Task_Info_Type;
587 -- System-specific attributes of the task as specified by the
590 Analyzer : System.Stack_Usage.Stack_Analyzer;
591 -- For storing informations used to measure the stack usage
593 Global_Task_Lock_Nesting : Natural;
594 -- This is the current nesting level of calls to
595 -- System.Tasking.Initialization.Lock_Task. This allows a task to call
596 -- Lock_Task multiple times without deadlocking. A task only locks
597 -- Global_Task_Lock when its Global_Task_Lock_Nesting goes from 0 to 1,
598 -- and only unlocked when it goes from 1 to 0.
600 -- Protection: Only accessed by Self
602 Fall_Back_Handler : Termination_Handler;
603 -- This is the fall-back handler that applies to the dependent tasks of
606 -- Protection: Self.L
608 Specific_Handler : Termination_Handler;
609 -- This is the specific handler that applies only to this task, and not
610 -- any of its dependent tasks.
612 -- Protection: Self.L
615 ---------------------------------------
616 -- Restricted_Ada_Task_Control_Block --
617 ---------------------------------------
619 -- This type should only be used by the restricted GNARLI and by restricted
620 -- GNULL implementations to allocate an ATCB (see System.Task_Primitives.
621 -- Operations.New_ATCB) that will take significantly less memory.
623 -- Note that the restricted GNARLI should only access fields that are
624 -- present in the Restricted_Ada_Task_Control_Block structure.
626 type Restricted_Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is
628 Common : Common_ATCB;
629 -- The common part between various tasking implementations
631 Entry_Call : aliased Restricted_Entry_Call_Record;
632 -- Protection: This field is used on entry call "queues" associated
633 -- with protected objects, and is protected by the protected object
636 pragma Suppress_Initialization (Restricted_Ada_Task_Control_Block);
638 Interrupt_Manager_ID : Task_Id;
639 -- This task ID is declared here to break circular dependencies.
640 -- Also declare Interrupt_Manager_ID after Task_Id is known, to avoid
641 -- generating unneeded finalization code.
643 -----------------------
644 -- List of all Tasks --
645 -----------------------
647 All_Tasks_List : Task_Id;
648 -- Global linked list of all tasks
650 ------------------------------------------
651 -- Regular (non restricted) definitions --
652 ------------------------------------------
654 --------------------------------
655 -- Master Related Definitions --
656 --------------------------------
658 subtype Master_Level is Integer;
659 subtype Master_ID is Master_Level;
661 -- Normally, a task starts out with internal master nesting level one
662 -- larger than external master nesting level. It is incremented to one by
663 -- Enter_Master, which is called in the task body only if the compiler
664 -- thinks the task may have dependent tasks. It is set to 1 for the
665 -- environment task, the level 2 is reserved for server tasks of the
666 -- run-time system (the so called "independent tasks"), and the level 3 is
667 -- for the library level tasks. Foreign threads which are detected by
668 -- the run-time have a level of 0, allowing these tasks to be easily
669 -- distinguished if needed.
671 Foreign_Task_Level : constant Master_Level := 0;
672 Environment_Task_Level : constant Master_Level := 1;
673 Independent_Task_Level : constant Master_Level := 2;
674 Library_Task_Level : constant Master_Level := 3;
676 ------------------------------
677 -- Task size, priority info --
678 ------------------------------
680 Unspecified_Priority : constant Integer := System.Priority'First - 1;
682 Priority_Not_Boosted : constant Integer := System.Priority'First - 1;
683 -- Definition of Priority actually has to come from the RTS configuration
685 subtype Rendezvous_Priority is Integer
686 range Priority_Not_Boosted .. System.Any_Priority'Last;
688 ------------------------------------
689 -- Rendezvous related definitions --
690 ------------------------------------
692 No_Rendezvous : constant := 0;
694 Max_Select : constant Integer := Integer'Last;
697 subtype Select_Index is Integer range No_Rendezvous .. Max_Select;
698 -- type Select_Index is range No_Rendezvous .. Max_Select;
700 subtype Positive_Select_Index is
701 Select_Index range 1 .. Select_Index'Last;
703 type Accept_Alternative is record
705 S : Task_Entry_Index;
709 array (Positive_Select_Index range <>) of Accept_Alternative;
711 type Accept_List_Access is access constant Accept_List;
713 -----------------------------------
714 -- ATC_Level related definitions --
715 -----------------------------------
717 Max_ATC_Nesting : constant Natural := 20;
719 subtype ATC_Level_Base is Integer range 0 .. Max_ATC_Nesting;
721 ATC_Level_Infinity : constant ATC_Level_Base := ATC_Level_Base'Last;
723 subtype ATC_Level is ATC_Level_Base range 0 .. ATC_Level_Base'Last - 1;
725 subtype ATC_Level_Index is ATC_Level range 1 .. ATC_Level'Last;
727 ----------------------------------
728 -- Entry_Call_Record definition --
729 ----------------------------------
731 type Entry_Call_Record is record
737 State : Entry_Call_State;
738 pragma Atomic (State);
739 -- Indicates part of the state of the call
741 -- Protection: If the call is not on a queue, it should only be
742 -- accessed by Self, and Self does not need any lock to modify this
743 -- field. Once the call is on a queue, the value should be something
744 -- other than Done unless it is cancelled, and access is controller by
745 -- the "server" of the queue -- i.e., the lock of Checked_To_Protection
746 -- (Call_Target) if the call record is on the queue of a PO, or the
747 -- lock of Called_Target if the call is on the queue of a task. See
748 -- comments on type declaration for more details.
750 Uninterpreted_Data : System.Address;
751 -- Data passed by the compiler
753 Exception_To_Raise : Ada.Exceptions.Exception_Id;
754 -- The exception to raise once this call has been completed without
757 Prev : Entry_Call_Link;
759 Next : Entry_Call_Link;
762 -- One of Self and Level are redundant in this implementation, since
763 -- each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must
764 -- have access to the entry call record to be reading this, we could
765 -- get Self from Level, or Level from Self. However, this requires
766 -- non-portable address arithmetic.
770 Prio : System.Any_Priority;
772 -- The above fields are those that there may be some hope of packing.
773 -- They are gathered together to allow for compilers that lay records
774 -- out contiguously, to allow for such packing.
776 Called_Task : Task_Id;
777 pragma Atomic (Called_Task);
778 -- Use for task entry calls. The value is null if the call record is
779 -- not in use. Conversely, unless State is Done and Onqueue is false,
780 -- Called_Task points to an ATCB.
782 -- Protection: Called_Task.L
784 Called_PO : System.Address;
785 pragma Atomic (Called_PO);
786 -- Similar to Called_Task but for protected objects
788 -- Note that the previous implementation tried to merge both
789 -- Called_Task and Called_PO but this ended up in many unexpected
790 -- complications (e.g having to add a magic number in the ATCB, which
791 -- caused gdb lots of confusion) with no real gain since the
792 -- Lock_Server implementation still need to loop around chasing for
793 -- pointer changes even with a single pointer.
795 Acceptor_Prev_Call : Entry_Call_Link;
796 -- For task entry calls only
798 Acceptor_Prev_Priority : Rendezvous_Priority := Priority_Not_Boosted;
799 -- For task entry calls only. The priority of the most recent prior
800 -- call being serviced. For protected entry calls, this function should
801 -- be performed by GNULLI ceiling locking.
803 Cancellation_Attempted : Boolean := False;
804 pragma Atomic (Cancellation_Attempted);
805 -- Cancellation of the call has been attempted.
806 -- Consider merging this into State???
808 With_Abort : Boolean := False;
809 -- Tell caller whether the call may be aborted
810 -- ??? consider merging this with Was_Abortable state
812 Needs_Requeue : Boolean := False;
813 -- Temporary to tell acceptor of task entry call that
814 -- Exceptional_Complete_Rendezvous needs to do requeue.
817 ------------------------------------
818 -- Task related other definitions --
819 ------------------------------------
821 type Access_Address is access all System.Address;
822 -- Anonymous pointer used to implement task attributes (see s-tataat.adb
825 pragma No_Strict_Aliasing (Access_Address);
826 -- This type is used in contexts where aliasing may be an issue (see
827 -- for example s-tataat.adb), so we avoid any incorrect aliasing
830 ----------------------------------------------
831 -- Ada_Task_Control_Block (ATCB) definition --
832 ----------------------------------------------
834 type Entry_Call_Array is array (ATC_Level_Index) of
835 aliased Entry_Call_Record;
837 type Direct_Index is range 0 .. Parameters.Default_Attribute_Count;
838 subtype Direct_Index_Range is Direct_Index range 1 .. Direct_Index'Last;
839 -- Attributes with indices in this range are stored directly in the task
840 -- control block. Such attributes must be Address-sized. Other attributes
841 -- will be held in dynamically allocated records chained off of the task
844 type Direct_Attribute_Element is mod Memory_Size;
845 pragma Atomic (Direct_Attribute_Element);
847 type Direct_Attribute_Array is
848 array (Direct_Index_Range) of aliased Direct_Attribute_Element;
850 type Direct_Index_Vector is mod 2 ** Parameters.Default_Attribute_Count;
851 -- This is a bit-vector type, used to store information about
852 -- the usage of the direct attribute fields.
854 type Task_Serial_Number is mod 2 ** 64;
855 -- Used to give each task a unique serial number
857 type Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is record
858 Common : Common_ATCB;
859 -- The common part between various tasking implementations
861 Entry_Calls : Entry_Call_Array;
862 -- An array of entry calls
864 -- Protection: The elements of this array are on entry call queues
865 -- associated with protected objects or task entries, and are protected
866 -- by the protected object lock or Acceptor.L, respectively.
868 Entry_Names : Entry_Names_Array_Access := null;
869 -- An array of string names which denotes entry [family member] names.
870 -- The structure is indexed by task entry index and contains Entry_Num
873 New_Base_Priority : System.Any_Priority;
874 -- New value for Base_Priority (for dynamic priorities package)
876 -- Protection: Self.L
878 Open_Accepts : Accept_List_Access;
879 -- This points to the Open_Accepts array of accept alternatives passed
880 -- to the RTS by the compiler-generated code to Selective_Wait. It is
881 -- non-null iff this task is ready to accept an entry call.
883 -- Protection: Self.L
885 Chosen_Index : Select_Index;
886 -- The index in Open_Accepts of the entry call accepted by a selective
887 -- wait executed by this task.
889 -- Protection: Written by both Self and Caller. Usually protected by
890 -- Self.L. However, once the selection is known to have been written it
891 -- can be accessed without protection. This happens after Self has
892 -- updated it itself using information from a suspended Caller, or
893 -- after Caller has updated it and awakened Self.
895 Master_of_Task : Master_Level;
896 -- The task executing the master of this task, and the ID of this task's
897 -- master (unique only among masters currently active within Parent).
899 -- Protection: Set by Activator before Self is activated, and read
900 -- after Self is activated.
902 Master_Within : Master_Level;
903 -- The ID of the master currently executing within this task; that is,
904 -- the most deeply nested currently active master.
906 -- Protection: Only written by Self, and only read by Self or by
907 -- dependents when Self is attempting to exit a master. Since Self will
908 -- not write this field until the master is complete, the
909 -- synchronization should be adequate to prevent races.
911 Alive_Count : Integer := 0;
912 -- Number of tasks directly dependent on this task (including itself)
913 -- that are still "alive", i.e. not terminated.
915 -- Protection: Self.L
917 Awake_Count : Integer := 0;
918 -- Number of tasks directly dependent on this task (including itself)
919 -- still "awake", i.e., are not terminated and not waiting on a
920 -- terminate alternative.
922 -- Invariant: Awake_Count <= Alive_Count
924 -- Protection: Self.L
926 -- Beginning of flags
928 Aborting : Boolean := False;
929 pragma Atomic (Aborting);
930 -- Self is in the process of aborting. While set, prevents multiple
931 -- abort signals from being sent by different aborter while abort
932 -- is acted upon. This is essential since an aborter which calls
933 -- Abort_To_Level could set the Pending_ATC_Level to yet a lower level
934 -- (than the current level), may be preempted and would send the
935 -- abort signal when resuming execution. At this point, the abortee
936 -- may have completed abort to the proper level such that the
937 -- signal (and resulting abort exception) are not handled any more.
938 -- In other words, the flag prevents a race between multiple aborters
940 -- Protection: protected by atomic access.
942 ATC_Hack : Boolean := False;
943 pragma Atomic (ATC_Hack);
945 -- Temporary fix, to allow Undefer_Abort to reset Aborting in the
946 -- handler for Abort_Signal that encloses an async. entry call.
947 -- For the longer term, this should be done via code in the
950 Callable : Boolean := True;
951 -- It is OK to call entries of this task
953 Dependents_Aborted : Boolean := False;
954 -- This is set to True by whichever task takes responsibility for
955 -- aborting the dependents of this task.
957 -- Protection: Self.L
959 Interrupt_Entry : Boolean := False;
960 -- Indicates if one or more Interrupt Entries are attached to the task.
961 -- This flag is needed for cleaning up the Interrupt Entry bindings.
963 Pending_Action : Boolean := False;
964 -- Unified flag indicating some action needs to be take when abort
965 -- next becomes undeferred. Currently set if:
966 -- . Pending_Priority_Change is set
967 -- . Pending_ATC_Level is changed
968 -- . Requeue involving POs
969 -- (Abortable field may have changed and the Wait_Until_Abortable
970 -- has to recheck the abortable status of the call.)
971 -- . Exception_To_Raise is non-null
973 -- Protection: Self.L
975 -- This should never be reset back to False outside of the procedure
976 -- Do_Pending_Action, which is called by Undefer_Abort. It should only
977 -- be set to True by Set_Priority and Abort_To_Level.
979 Pending_Priority_Change : Boolean := False;
980 -- Flag to indicate pending priority change (for dynamic priorities
981 -- package). The base priority is updated on the next abort
982 -- completion point (aka. synchronization point).
984 -- Protection: Self.L
986 Terminate_Alternative : Boolean := False;
987 -- Task is accepting Select with Terminate Alternative
989 -- Protection: Self.L
993 -- Beginning of counts
995 ATC_Nesting_Level : ATC_Level := 1;
996 -- The dynamic level of ATC nesting (currently executing nested
997 -- asynchronous select statements) in this task.
999 -- Protection: Self_ID.L. Only Self reads or updates this field.
1000 -- Decrementing it deallocates an Entry_Calls component, and care must
1001 -- be taken that all references to that component are eliminated before
1002 -- doing the decrement. This in turn will require locking a protected
1003 -- object (for a protected entry call) or the Acceptor's lock (for a
1004 -- task entry call). No other task should attempt to read or modify
1007 Deferral_Level : Natural := 1;
1008 -- This is the number of times that Defer_Abort has been called by
1009 -- this task without a matching Undefer_Abort call. Abortion is only
1010 -- allowed when this zero. It is initially 1, to protect the task at
1013 -- Protection: Only updated by Self; access assumed to be atomic
1015 Pending_ATC_Level : ATC_Level_Base := ATC_Level_Infinity;
1016 -- The ATC level to which this task is currently being aborted. If the
1017 -- value is zero, the entire task has "completed". That may be via
1018 -- abort, exception propagation, or normal exit. If the value is
1019 -- ATC_Level_Infinity, the task is not being aborted to any level. If
1020 -- the value is positive, the task has not completed. This should ONLY
1021 -- be modified by Abort_To_Level and Exit_One_ATC_Level.
1023 -- Protection: Self.L
1025 Serial_Number : Task_Serial_Number;
1026 -- A growing number to provide some way to check locking rules/ordering
1028 Known_Tasks_Index : Integer := -1;
1029 -- Index in the System.Tasking.Debug.Known_Tasks array
1031 User_State : Long_Integer := 0;
1032 -- User-writeable location, for use in debugging tasks; also provides a
1033 -- simple task specific data.
1035 Direct_Attributes : Direct_Attribute_Array;
1036 -- For task attributes that have same size as Address
1038 Is_Defined : Direct_Index_Vector := 0;
1039 -- Bit I is 1 iff Direct_Attributes (I) is defined
1041 Indirect_Attributes : Access_Address;
1042 -- A pointer to chain of records for other attributes that are not
1043 -- address-sized, including all tagged types.
1045 Entry_Queues : Task_Entry_Queue_Array (1 .. Entry_Num);
1046 -- An array of task entry queues
1048 -- Protection: Self.L. Once a task has set Self.Stage to Completing, it
1049 -- has exclusive access to this field.
1052 --------------------
1053 -- Initialization --
1054 --------------------
1056 procedure Initialize;
1057 -- This procedure constitutes the first part of the initialization of the
1058 -- GNARL. This includes creating data structures to make the initial thread
1059 -- into the environment task. The last part of the initialization is done
1060 -- in System.Tasking.Initialization or System.Tasking.Restricted.Stages.
1061 -- All the initializations used to be in Tasking.Initialization, but this
1062 -- is no longer possible with the run time simplification (including
1063 -- optimized PO and the restricted run time) since one cannot rely on
1064 -- System.Tasking.Initialization being present, as was done before.
1066 procedure Initialize_ATCB
1068 Task_Entry_Point : Task_Procedure_Access;
1069 Task_Arg : System.Address;
1071 Elaborated : Access_Boolean;
1072 Base_Priority : System.Any_Priority;
1073 Task_Info : System.Task_Info.Task_Info_Type;
1074 Stack_Size : System.Parameters.Size_Type;
1076 Success : out Boolean);
1077 -- Initialize fields of a TCB and link into global TCB structures Call
1078 -- this only with abort deferred and holding RTS_Lock. Need more
1079 -- documentation, mention T, and describe Success ???
1083 Null_Task : constant Task_Id := null;
1085 type Activation_Chain is limited record
1089 -- Activation_Chain is an in-out parameter of initialization procedures and
1090 -- it must be passed by reference because the init proc may terminate
1091 -- abnormally after creating task components, and these must be properly
1092 -- registered for removal (Expunge_Unactivated_Tasks). The "limited" forces
1093 -- Activation_Chain to be a by-reference type; see RM-6.2(4).