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-2024, 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 3, or (at your option) any later ver- --
14 -- sion. GNAT 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. --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception, --
20 -- version 3.1, as published by the Free Software Foundation. --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
27 -- GNARL was developed by the GNARL team at Florida State University. --
28 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
30 ------------------------------------------------------------------------------
32 -- This package provides necessary type definitions for compiler interface
34 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
35 -- Any changes to this interface may require corresponding compiler changes.
38 with Ada
.Unchecked_Conversion
;
40 with System
.Multiprocessors
;
41 with System
.Parameters
;
42 with System
.Soft_Links
;
43 with System
.Stack_Usage
;
44 with System
.Task_Info
;
45 with System
.Task_Primitives
;
47 package System
.Tasking
is
54 -- The following rules must be followed at all times, to prevent
55 -- deadlock and generally ensure correct operation of locking.
57 -- Never lock a lock unless abort is deferred
59 -- Never undefer abort while holding a lock
61 -- Overlapping critical sections must be properly nested, and locks must
62 -- be released in LIFO order. E.g., the following is not allowed:
72 -- Locks with lower (smaller) level number cannot be locked
73 -- while holding a lock with a higher level number. (The level
75 -- 1. System.Tasking.PO_Simple.Protection.L (any PO lock)
76 -- 2. System.Tasking.Initialization.Global_Task_Lock (in body)
77 -- 3. System.Task_Primitives.Operations.Single_RTS_Lock
78 -- 4. System.Tasking.Ada_Task_Control_Block.LL.L (any TCB lock)
80 -- Clearly, there can be no circular chain of hold-and-wait
81 -- relationships involving locks in different ordering levels.
83 -- We used to have Global_Task_Lock before Protection.L but this was
84 -- clearly wrong since there can be calls to "new" inside protected
85 -- operations. The new ordering prevents these failures.
87 -- Sometimes we need to hold two ATCB locks at the same time. To allow us
88 -- to order the locking, each ATCB is given a unique serial number. If one
89 -- needs to hold locks on two ATCBs at once, the lock with lower serial
90 -- number must be locked first. We avoid holding three or more ATCB locks,
91 -- because that can easily lead to complications that cause race conditions
94 -- We don't always need to check the serial numbers, since the serial
95 -- numbers are assigned sequentially, and so:
97 -- . The parent of a task always has a lower serial number.
98 -- . The activator of a task always has a lower serial number.
99 -- . The environment task has a lower serial number than any other task.
100 -- . If the activator of a task is different from the task's parent,
101 -- the parent always has a lower serial number than the activator.
103 ---------------------------------
104 -- Task_Id related definitions --
105 ---------------------------------
107 type Ada_Task_Control_Block
;
109 type Task_Id
is access all Ada_Task_Control_Block
;
110 for Task_Id
'Size use System
.Task_Primitives
.Task_Address_Size
;
112 Null_Task
: constant Task_Id
;
114 type Task_List
is array (Positive range <>) of Task_Id
;
116 function Self
return Task_Id
;
117 pragma Inline
(Self
);
118 -- This is the compiler interface version of this function. Do not call
119 -- from the run-time system.
121 function To_Task_Id
is
122 new Ada
.Unchecked_Conversion
123 (System
.Task_Primitives
.Task_Address
, Task_Id
);
124 function To_Address
is
125 new Ada
.Unchecked_Conversion
126 (Task_Id
, System
.Task_Primitives
.Task_Address
);
128 -----------------------
129 -- Enumeration types --
130 -----------------------
134 -- TCB initialized but not task has not been created.
135 -- It cannot be executing.
138 -- -- ??? Temporarily at end of list for GDB compatibility
139 -- -- Task has been created and is being made Runnable.
142 -- For all states from here down, the task has been activated.
143 -- For all states from here down, except for Terminated, the task
145 -- Activator = null iff it has not yet completed activating.
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 select with terminate
163 -- Acceptor_Delay_Sleep,
164 -- -- ??? Temporarily at end of list for GDB compatibility
165 -- -- Task is waiting on an selective wait statement
168 -- Task is waiting on an entry call
171 -- Task is waiting to start the abortable part of an
172 -- asynchronous select statement.
175 -- Task is waiting on a select statement with only a delay
178 Master_Completion_Sleep
,
179 -- Master completion has two phases.
180 -- In Phase 1 the task is sleeping in Complete_Master
181 -- having completed a master within itself,
182 -- and is waiting for the tasks dependent on that master to become
183 -- terminated or waiting on a terminate Phase.
185 Master_Phase_2_Sleep
,
186 -- In Phase 2 the task is sleeping in Complete_Master
187 -- waiting for tasks on terminate alternatives to finish
190 -- The following are special uses of sleep, for server tasks
191 -- within the run-time system.
193 Interrupt_Server_Idle_Sleep
,
194 Interrupt_Server_Blocked_Interrupt_Sleep
,
199 -- The task has been held by Asynchronous_Task_Control.Hold_Task
201 Interrupt_Server_Blocked_On_Event_Flag
,
202 -- The task has been blocked on a system call waiting for a
203 -- completion event/signal to occur.
206 -- Task has been created and is being made Runnable
209 -- Task is waiting on an selective wait statement
213 (Simple_Call
, Conditional_Call
, Asynchronous_Call
, Timed_Call
);
215 type Select_Modes
is (Simple_Mode
, Else_Mode
, Terminate_Mode
, Delay_Mode
);
217 subtype Delay_Modes
is Integer;
219 -------------------------------
220 -- Entry related definitions --
221 -------------------------------
223 Null_Entry
: constant := 0;
225 Max_Entry
: constant := Integer'Last;
227 Interrupt_Entry
: constant := -2;
229 Cancelled_Entry
: constant := -1;
231 type Entry_Index
is range Interrupt_Entry
.. Max_Entry
;
233 Null_Task_Entry
: constant := Null_Entry
;
235 Max_Task_Entry
: constant := Max_Entry
;
237 type Task_Entry_Index
is new Entry_Index
238 range Null_Task_Entry
.. Max_Task_Entry
;
240 type Entry_Call_Record
;
242 type Entry_Call_Link
is access all Entry_Call_Record
;
244 type Entry_Queue
is record
245 Head
: Entry_Call_Link
;
246 Tail
: Entry_Call_Link
;
249 type Task_Entry_Queue_Array
is
250 array (Task_Entry_Index
range <>) of Entry_Queue
;
252 -- A data structure which contains the string names of entries and entry
255 type String_Access
is access all String;
257 ----------------------------------
258 -- Entry_Call_Record definition --
259 ----------------------------------
261 type Entry_Call_State
is
263 -- the call is not abortable, and never can be
266 -- the call is not abortable, but may become so
269 -- the call is not abortable, but once was
272 -- the call is abortable
275 -- the call has been completed
278 -- the call was asynchronous, and was cancelled
280 pragma Ordered
(Entry_Call_State
);
282 -- Never_Abortable is used for calls that are made in a abort deferred
283 -- region (see ARM 9.8(5-11), 9.8 (20)). Such a call is never abortable.
285 -- The Was_ vs. Not_Yet_ distinction is needed to decide whether it is OK
286 -- to advance into the abortable part of an async. select stmt. That is
287 -- allowed iff the mode is Now_ or Was_.
289 -- Done indicates the call has been completed, without cancellation, or no
290 -- call has been made yet at this ATC nesting level, and so aborting the
291 -- call is no longer an issue. Completion of the call does not necessarily
292 -- indicate "success"; the call may be returning an exception if
293 -- Exception_To_Raise is non-null.
295 -- Cancelled indicates the call was cancelled, and so aborting the call is
296 -- no longer an issue.
298 -- The call is on an entry queue unless State >= Done, in which case it may
299 -- or may not be still Onqueue.
301 -- Please do not modify the order of the values, without checking all uses
302 -- of this type. We rely on partial "monotonicity" of
303 -- Entry_Call_Record.State to avoid locking when we access this value for
304 -- certain tests. In particular:
306 -- 1) Once State >= Done, we can rely that the call has been
307 -- completed. If State >= Done, it will not
308 -- change until the task does another entry call at this level.
310 -- 2) Once State >= Was_Abortable, we can rely that the call has
311 -- been queued abortably at least once, and so the check for
312 -- whether it is OK to advance to the abortable part of an
313 -- async. select statement does not need to lock anything.
315 type Restricted_Entry_Call_Record
is record
321 State
: Entry_Call_State
;
322 pragma Atomic
(State
);
323 -- Indicates part of the state of the call.
325 -- Protection: If the call is not on a queue, it should only be
326 -- accessed by Self, and Self does not need any lock to modify this
329 -- Once the call is on a queue, the value should be something other
330 -- than Done unless it is cancelled, and access is controller by the
331 -- "server" of the queue -- i.e., the lock of Checked_To_Protection
332 -- (Call_Target) if the call record is on the queue of a PO, or the
333 -- lock of Called_Target if the call is on the queue of a task. See
334 -- comments on type declaration for more details.
336 Uninterpreted_Data
: System
.Address
;
337 -- Data passed by the compiler
339 Exception_To_Raise
: Ada
.Exceptions
.Exception_Id
;
340 -- The exception to raise once this call has been completed without
343 pragma Suppress_Initialization
(Restricted_Entry_Call_Record
);
345 -------------------------------------------
346 -- Task termination procedure definition --
347 -------------------------------------------
349 -- We need to redefine here these types (already defined in
350 -- Ada.Task_Termination) for avoiding circular dependencies.
352 type Cause_Of_Termination
is (Normal
, Abnormal
, Unhandled_Exception
);
353 -- Possible causes for task termination:
355 -- Normal means that the task terminates due to completing the
356 -- last sentence of its body, or as a result of waiting on a
357 -- terminate alternative.
359 -- Abnormal means that the task terminates because it is being aborted
361 -- handled_Exception means that the task terminates because of exception
362 -- raised by the execution of its task_body.
364 type Termination_Handler
is access protected procedure
365 (Cause
: Cause_Of_Termination
;
367 X
: Ada
.Exceptions
.Exception_Occurrence
);
368 -- Used to represent protected procedures to be executed when task
371 ------------------------------------
372 -- Dispatching domain definitions --
373 ------------------------------------
375 -- We need to redefine here these types (already defined in
376 -- System.Multiprocessor.Dispatching_Domains) for avoiding circular
379 type Dispatching_Domain
is
380 array (System
.Multiprocessors
.CPU
range <>) of Boolean;
381 -- A dispatching domain needs to contain the set of processors belonging
382 -- to it. This is a processor mask where a True indicates that the
383 -- processor belongs to the dispatching domain.
384 -- Do not use the full range of CPU_Range because it would create a very
385 -- long array. This way we can use the exact range of processors available
388 type Dispatching_Domain_Access
is access Dispatching_Domain
;
390 System_Domain
: Dispatching_Domain_Access
;
391 -- All processors belong to default system dispatching domain at start up.
392 -- We use a pointer which creates the actual variable for the reasons
393 -- explained bellow in Dispatching_Domain_Tasks.
395 Dispatching_Domains_Frozen
: Boolean := False;
396 -- True when the main procedure has been called. Hence, no new dispatching
397 -- domains can be created when this flag is True.
399 type Array_Allocated_Tasks
is
400 array (System
.Multiprocessors
.CPU
range <>) of Natural;
401 -- At start-up time, we need to store the number of tasks attached to
402 -- concrete processors within the system domain (we can only create
403 -- dispatching domains with processors belonging to the system domain and
404 -- without tasks allocated).
406 type Array_Allocated_Tasks_Access
is access Array_Allocated_Tasks
;
408 Dispatching_Domain_Tasks
: Array_Allocated_Tasks_Access
;
409 -- We need to store whether there are tasks allocated to concrete
410 -- processors in the default system dispatching domain because we need to
411 -- check it before creating a new dispatching domain. Two comments about
412 -- why we use a pointer here and not in package Dispatching_Domains:
414 -- 1) We use an array created dynamically in procedure Initialize which
415 -- is called at the beginning of the initialization of the run-time
416 -- library. Declaring a static array here in the spec would not work
417 -- across different installations because it would get the value of
418 -- Number_Of_CPUs from the machine where the run-time library is built,
419 -- and not from the machine where the application is executed. That is
420 -- the reason why we create the array (CPU'First .. Number_Of_CPUs) at
421 -- execution time in the procedure body, ensuring that the function
422 -- Number_Of_CPUs is executed at execution time (the same trick as we
423 -- use for System_Domain).
425 -- 2) We have moved this declaration from package Dispatching_Domains
426 -- because when we use a pragma CPU, the affinity is passed through the
427 -- call to Create_Task. Hence, at this point, we may need to update the
428 -- number of tasks associated to the processor, but we do not want to
429 -- force a dependency from this package on Dispatching_Domains.
431 ------------------------------------
432 -- Task related other definitions --
433 ------------------------------------
435 type Activation_Chain
is limited private;
436 -- Linked list of to-be-activated tasks, linked through
437 -- Activation_Link. The order of tasks on the list is irrelevant, because
438 -- the priority rules will ensure that they actually start activating in
441 type Activation_Chain_Access
is access all Activation_Chain
;
443 type Task_Procedure_Access
is access procedure (Arg
: System
.Address
);
445 type Access_Boolean
is access all Boolean;
447 function Detect_Blocking
return Boolean;
448 pragma Inline
(Detect_Blocking
);
449 -- Return whether the Detect_Blocking pragma is enabled
451 function Storage_Size
(T
: Task_Id
) return System
.Parameters
.Size_Type
;
452 -- Retrieve from the TCB of the task the allocated size of its stack,
453 -- either the system default or the size specified by a pragma. This is in
454 -- general a non-static value that can depend on discriminants of the task.
456 type Bit_Array
is array (Integer range <>) of Boolean;
457 pragma Pack
(Bit_Array
);
459 subtype Debug_Event_Array
is Bit_Array
(1 .. 16);
461 Global_Task_Debug_Event_Set
: Boolean := False;
462 -- Set True when running under debugger control and a task debug event
463 -- signal has been requested.
465 ----------------------------------------------
466 -- Ada_Task_Control_Block (ATCB) definition --
467 ----------------------------------------------
469 -- Notes on protection (synchronization) of TRTS data structures
471 -- Any field of the TCB can be written by the activator of a task when the
472 -- task is created, since no other task can access the new task's
473 -- state until creation is complete.
475 -- The protection for each field is described in a comment starting with
478 -- When a lock is used to protect an ATCB field, this lock is simply named
480 -- Some protection is described in terms of tasks related to the
481 -- ATCB being protected. These are:
483 -- Self: The task which is controlled by this ATCB
484 -- Acceptor: A task accepting a call from Self
485 -- Caller: A task calling an entry of Self
486 -- Parent: The task executing the master on which Self depends
487 -- Dependent: A task dependent on Self
488 -- Activator: The task that created Self and initiated its activation
489 -- Created: A task created and activated by Self
491 -- Note: The order of the fields is important to implement efficiently
492 -- tasking support under gdb.
493 -- Currently gdb relies on the order of the State, Parent, Base_Priority,
494 -- Task_Image, Task_Image_Len, Call and LL fields.
496 -------------------------
497 -- Common ATCB section --
498 -------------------------
500 -- Section used by all GNARL implementations (regular and restricted)
502 type Common_ATCB
is limited record
504 pragma Atomic
(State
);
505 -- Encodes some basic information about the state of a task,
506 -- including whether it has been activated, whether it is sleeping,
507 -- and whether it is terminated.
509 -- Protection: Self.L
512 -- The task on which this task depends.
513 -- See also Master_Level and Master_Within.
515 Base_Priority
: System
.Any_Priority
;
516 -- Base priority, not changed during entry calls, only changed
517 -- via dynamic priorities package.
519 -- Protection: Only written by Self, accessed by anyone
521 Base_CPU
: System
.Multiprocessors
.CPU_Range
;
522 -- Base CPU, only changed via dispatching domains package.
524 -- Protection: Self.L
526 Current_Priority
: System
.Any_Priority
;
527 -- Active priority, except that the effects of protected object
528 -- priority ceilings are not reflected. This only reflects explicit
529 -- priority changes and priority inherited through task activation
532 -- Ada 95 notes: In Ada 95, this field will be transferred to the
533 -- Priority field of an Entry_Calls component when an entry call is
534 -- initiated. The Priority of the Entry_Calls component will not change
535 -- for the duration of the call. The accepting task can use it to boost
536 -- its own priority without fear of its changing in the meantime.
538 -- This can safely be used in the priority ordering of entry queues.
539 -- Once a call is queued, its priority does not change.
541 -- Since an entry call cannot be made while executing a protected
542 -- action, the priority of a task will never reflect a priority ceiling
543 -- change at the point of an entry call.
545 -- Protection: Only written by Self, and only accessed when Acceptor
546 -- accepts an entry or when Created activates, at which points Self is
549 Protected_Action_Nesting
: Natural;
550 pragma Atomic
(Protected_Action_Nesting
);
551 -- The dynamic level of protected action nesting for this task. This
552 -- field is needed for checking whether potentially blocking operations
553 -- are invoked from protected actions. pragma Atomic is used because it
554 -- can be read/written from protected interrupt handlers.
556 Task_Image
: String (1 .. System
.Parameters
.Max_Task_Image_Length
);
557 -- Hold a string that provides a readable id for task, built from the
558 -- variable of which it is a value or component.
560 Task_Image_Len
: Natural;
561 -- Actual length of Task_Image
563 Call
: Entry_Call_Link
;
564 -- The entry call that has been accepted by this task.
566 -- Protection: Self.L. Self will modify this field when Self.Accepting
567 -- is False, and will not need the mutex to do so. Once a task sets
568 -- Pending_ATC_Level = Level_Completed_Task, no other task can access
571 LL
: aliased Task_Primitives
.Private_Data
;
572 -- Control block used by the underlying low-level tasking service
575 -- Protection: This is used only by the GNULLI implementation, which
576 -- takes care of all of its synchronization.
578 Task_Arg
: System
.Address
;
579 -- The argument to task procedure. Provide a handle for discriminant
582 -- Protection: Part of the synchronization between Self and Activator.
583 -- Activator writes it, once, before Self starts executing. Thereafter,
584 -- Self only reads it.
586 Task_Alternate_Stack
: System
.Address
;
587 -- The address of the alternate signal stack for this task, if any
589 -- Protection: Only accessed by Self
591 Task_Entry_Point
: Task_Procedure_Access
;
592 -- Information needed to call the procedure containing the code for
593 -- the body of this task.
595 -- Protection: Part of the synchronization between Self and Activator.
596 -- Activator writes it, once, before Self starts executing. Self reads
597 -- it, once, as part of its execution.
599 Compiler_Data
: System
.Soft_Links
.TSD
;
600 -- Task-specific data needed by the compiler to store per-task
603 -- Protection: Only accessed by Self
605 All_Tasks_Link
: Task_Id
;
606 -- Used to link this task to the list of all tasks in the system
608 -- Protection: RTS_Lock
610 Activation_Link
: Task_Id
;
611 -- Used to link this task to a list of tasks to be activated
613 -- Protection: Only used by Activator
616 pragma Atomic
(Activator
);
617 -- The task that created this task, either by declaring it as a task
618 -- object or by executing a task allocator. The value is null iff Self
619 -- has completed activation.
621 -- Protection: Set by Activator before Self is activated, and
622 -- only modified by Self after that. Can be read by any task via
623 -- Ada.Task_Identification.Activation_Is_Complete; hence Atomic.
625 Wait_Count
: Natural;
626 -- This count is used by a task that is waiting for other tasks. At all
627 -- other times, the value should be zero. It is used differently in
628 -- several different states. Since a task cannot be in more than one of
629 -- these states at the same time, a single counter suffices.
631 -- Protection: Self.L
635 -- This is the number of tasks that this task is activating, i.e. the
636 -- children that have started activation but have not completed it.
638 -- Protection: Self.L and Created.L. Both mutexes must be locked, since
639 -- Self.Activation_Count and Created.State must be synchronized.
641 -- Master_Completion_Sleep (phase 1)
643 -- This is the number dependent tasks of a master being completed by
644 -- Self that are activated, but have not yet terminated, and are not
645 -- waiting on a terminate alternative.
647 -- Master_Completion_2_Sleep (phase 2)
649 -- This is the count of tasks dependent on a master being completed by
650 -- Self which are waiting on a terminate alternative.
652 Elaborated
: Access_Boolean
;
653 -- Pointer to a flag indicating that this task's body has been
654 -- elaborated. The flag is created and managed by the
655 -- compiler-generated code.
657 -- Protection: The field itself is only accessed by Activator. The flag
658 -- that it points to is updated by Master and read by Activator; access
659 -- is assumed to be atomic.
661 Activation_Failed
: Boolean;
662 -- Set to True if activation of a chain of tasks fails,
663 -- so that the activator should raise Tasking_Error.
665 Task_Info
: System
.Task_Info
.Task_Info_Type
;
666 -- System-specific attributes of the task as specified by the
669 Analyzer
: System
.Stack_Usage
.Stack_Analyzer
;
670 -- For storing information used to measure the stack usage
672 Global_Task_Lock_Nesting
: Natural;
673 -- This is the current nesting level of calls to
674 -- System.Tasking.Initialization.Lock_Task. This allows a task to call
675 -- Lock_Task multiple times without deadlocking. A task only locks
676 -- Global_Task_Lock when its Global_Task_Lock_Nesting goes from 0 to 1,
677 -- and only unlocked when it goes from 1 to 0.
679 -- Protection: Only accessed by Self
681 Fall_Back_Handler
: Termination_Handler
;
682 -- This is the fall-back handler that applies to the dependent tasks of
685 -- Protection: Self.L
687 Specific_Handler
: Termination_Handler
;
688 -- This is the specific handler that applies only to this task, and not
689 -- any of its dependent tasks.
691 -- Protection: Self.L
693 Debug_Events
: Debug_Event_Array
;
694 -- Word length array of per task debug events, of which 11 kinds are
695 -- currently defined in System.Tasking.Debugging package.
697 Domain
: Dispatching_Domain_Access
;
698 -- Domain is the dispatching domain to which the task belongs. It is
699 -- only changed via dispatching domains package. This field is made
700 -- part of the Common_ATCB, even when restricted run-times (namely
701 -- Ravenscar) do not use it, because this way the field is always
702 -- available to the underlying layers to set the affinity and we do not
703 -- need to do different things depending on the situation.
705 -- Protection: Self.L
708 ---------------------------------------
709 -- Restricted_Ada_Task_Control_Block --
710 ---------------------------------------
712 -- This type should only be used by the restricted GNARLI and by restricted
713 -- GNULL implementations to allocate an ATCB (see System.Task_Primitives.
714 -- Operations.New_ATCB) that will take significantly less memory.
716 -- Note that the restricted GNARLI should only access fields that are
717 -- present in the Restricted_Ada_Task_Control_Block structure.
719 type Restricted_Ada_Task_Control_Block
(Entry_Num
: Task_Entry_Index
) is
721 Common
: Common_ATCB
;
722 -- The common part between various tasking implementations
724 Entry_Call
: aliased Restricted_Entry_Call_Record
;
725 -- Protection: This field is used on entry call "queues" associated
726 -- with protected objects, and is protected by the protected object
729 pragma Suppress_Initialization
(Restricted_Ada_Task_Control_Block
);
731 Interrupt_Manager_ID
: Task_Id
;
732 -- This task ID is declared here to break circular dependencies.
733 -- Also declare Interrupt_Manager_ID after Task_Id is known, to avoid
734 -- generating unneeded finalization code.
736 -----------------------
737 -- List of all Tasks --
738 -----------------------
740 All_Tasks_List
: Task_Id
;
741 -- Global linked list of all tasks
743 ------------------------------------------
744 -- Regular (non restricted) definitions --
745 ------------------------------------------
747 --------------------------------
748 -- Master Related Definitions --
749 --------------------------------
751 subtype Master_Level
is Integer;
752 subtype Master_ID
is Master_Level
;
754 -- Normally, a task starts out with internal master nesting level one
755 -- larger than external master nesting level. It is incremented by one by
756 -- Enter_Master, which is called in the task body only if the compiler
757 -- thinks the task may have dependent tasks. It is set to 1 for the
758 -- environment task, the level 2 is reserved for server tasks of the
759 -- run-time system (the so called "independent tasks"), and the level 3 is
760 -- for the library level tasks. Foreign threads which are detected by
761 -- the run-time have a level of 0, allowing these tasks to be easily
762 -- distinguished if needed.
764 Foreign_Task_Level
: constant Master_Level
:= 0;
765 Environment_Task_Level
: constant Master_Level
:= 1;
766 Independent_Task_Level
: constant Master_Level
:= 2;
767 Library_Task_Level
: constant Master_Level
:= 3;
768 -- Note that the value of Library_Task_Level is also hard coded in the
769 -- compiler, see Rtsfind.Library_Task_Level. The two should be kept in
776 Unspecified_Priority
: constant Integer := -1;
777 -- Indicates that a task has an unspecified priority. This is hardcoded as
778 -- -1 rather than System.Priority'First - 1 as the value needs to be used
779 -- in init.c to specify that the main task has no specified priority.
781 Priority_Not_Boosted
: constant Integer := System
.Priority
'First - 1;
782 -- Definition of Priority actually has to come from the RTS configuration
784 subtype Rendezvous_Priority
is Integer
785 range Priority_Not_Boosted
.. System
.Any_Priority
'Last;
791 Unspecified_CPU
: constant := -1;
792 -- No affinity specified
794 ------------------------------------
795 -- Rendezvous related definitions --
796 ------------------------------------
798 No_Rendezvous
: constant := 0;
800 Max_Select
: constant Integer := Integer'Last;
803 subtype Select_Index
is Integer range No_Rendezvous
.. Max_Select
;
804 -- type Select_Index is range No_Rendezvous .. Max_Select;
806 subtype Positive_Select_Index
is
807 Select_Index
range 1 .. Select_Index
'Last;
809 type Accept_Alternative
is record
811 S
: Task_Entry_Index
;
815 array (Positive_Select_Index
range <>) of Accept_Alternative
;
817 type Accept_List_Access
is access constant Accept_List
;
819 -----------------------------------
820 -- ATC_Level related definitions --
821 -----------------------------------
823 Max_ATC_Nesting
: constant Natural := 20;
824 -- The maximum number of nested asynchronous select statements supported
827 subtype ATC_Level_Base
is Integer range -1 .. Max_ATC_Nesting
;
828 -- Indicates the number of nested asynchronous task control statements
829 -- or entries a task is in.
831 Level_Completed_Task
: constant ATC_Level_Base
:= -1;
832 -- ATC_Level of a task that has "completed". A task reaches the completed
833 -- state after an abort, exception propagation, or normal exit.
835 Level_No_ATC_Occurring
: constant ATC_Level_Base
:= 0;
836 -- ATC_Level of a task not executing a entry call or an asynchronous
839 Level_No_Pending_Abort
: constant ATC_Level_Base
:= ATC_Level_Base
'Last;
840 -- ATC_Level when there is no pending abort
842 subtype ATC_Level
is ATC_Level_Base
range
843 Level_No_ATC_Occurring
.. Level_No_Pending_Abort
- 1;
844 -- Nested ATC_Levels valid during the execution of a task
846 subtype ATC_Level_Index
is ATC_Level
range
847 Level_No_ATC_Occurring
+ 1 .. ATC_Level
'Last;
848 -- ATC_Levels valid when a task is executing an entry call or asynchronous
849 -- task control statements.
851 ----------------------------------
852 -- Entry_Call_Record definition --
853 ----------------------------------
855 type Entry_Call_Record
is record
861 State
: Entry_Call_State
;
862 pragma Atomic
(State
);
863 -- Indicates part of the state of the call
865 -- Protection: If the call is not on a queue, it should only be
866 -- accessed by Self, and Self does not need any lock to modify this
867 -- field. Once the call is on a queue, the value should be something
868 -- other than Done unless it is cancelled, and access is controller by
869 -- the "server" of the queue -- i.e., the lock of Checked_To_Protection
870 -- (Call_Target) if the call record is on the queue of a PO, or the
871 -- lock of Called_Target if the call is on the queue of a task. See
872 -- comments on type declaration for more details.
874 Uninterpreted_Data
: System
.Address
;
875 -- Data passed by the compiler
877 Exception_To_Raise
: Ada
.Exceptions
.Exception_Id
;
878 -- The exception to raise once this call has been completed without
881 Prev
: Entry_Call_Link
;
883 Next
: Entry_Call_Link
;
886 -- One of Self and Level are redundant in this implementation, since
887 -- each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must
888 -- have access to the entry call record to be reading this, we could
889 -- get Self from Level, or Level from Self. However, this requires
890 -- non-portable address arithmetic.
894 Prio
: System
.Any_Priority
;
896 -- The above fields are those that there may be some hope of packing.
897 -- They are gathered together to allow for compilers that lay records
898 -- out contiguously, to allow for such packing.
900 Called_Task
: Task_Id
;
901 pragma Atomic
(Called_Task
);
902 -- Use for task entry calls. The value is null if the call record is
903 -- not in use. Conversely, unless State is Done and Onqueue is false,
904 -- Called_Task points to an ATCB.
906 -- Protection: Called_Task.L
908 Called_PO
: System
.Address
;
909 pragma Atomic
(Called_PO
);
910 -- Similar to Called_Task but for protected objects
912 -- Note that the previous implementation tried to merge both
913 -- Called_Task and Called_PO but this ended up in many unexpected
914 -- complications (e.g having to add a magic number in the ATCB, which
915 -- caused gdb lots of confusion) with no real gain since the
916 -- Lock_Server implementation still need to loop around chasing for
917 -- pointer changes even with a single pointer.
919 Acceptor_Prev_Call
: Entry_Call_Link
;
920 -- For task entry calls only
922 Acceptor_Prev_Priority
: Rendezvous_Priority
:= Priority_Not_Boosted
;
923 -- For task entry calls only. The priority of the most recent prior
924 -- call being serviced. For protected entry calls, this function should
925 -- be performed by GNULLI ceiling locking.
927 Cancellation_Attempted
: Boolean := False;
928 pragma Atomic
(Cancellation_Attempted
);
929 -- Cancellation of the call has been attempted.
930 -- Consider merging this into State???
932 With_Abort
: Boolean := False;
933 -- Tell caller whether the call may be aborted
934 -- ??? consider merging this with Was_Abortable state
936 Needs_Requeue
: Boolean := False;
937 -- Temporary to tell acceptor of task entry call that
938 -- Exceptional_Complete_Rendezvous needs to do requeue.
941 ------------------------------------
942 -- Task related other definitions --
943 ------------------------------------
945 type Access_Address
is access all System
.Address
;
946 -- Anonymous pointer used to implement task attributes (see s-tataat.adb
949 pragma No_Strict_Aliasing
(Access_Address
);
950 -- This type is used in contexts where aliasing may be an issue (see
951 -- for example s-tataat.adb), so we avoid any incorrect aliasing
954 ----------------------------------------------
955 -- Ada_Task_Control_Block (ATCB) definition --
956 ----------------------------------------------
958 type Entry_Call_Array
is array (ATC_Level_Index
) of
959 aliased Entry_Call_Record
;
961 type Attribute_Array
is
962 array (1 .. Parameters
.Max_Attribute_Count
) of System
.Address
;
963 pragma Atomic_Components
(Attribute_Array
);
964 -- Array of task attributes. The value (System.Address) will either be
965 -- converted to a task attribute if it fits, or to a pointer to a record
966 -- by Ada.Task_Attributes.
968 type Task_Serial_Number
is mod 2 ** Long_Long_Integer'Size;
969 -- Used to give each task a unique serial number. We want 64-bits for this
970 -- type to get as much uniqueness as possible (2**64 is operationally
971 -- infinite in this context, but 2**32 perhaps could recycle). We use
972 -- Long_Long_Integer (which in the normal case is always 64-bits) rather
973 -- than 64-bits explicitly to allow codepeer to analyze this unit when
974 -- a target configuration file forces the maximum integer size to 32.
976 type Ada_Task_Control_Block
(Entry_Num
: Task_Entry_Index
) is limited record
977 Common
: Common_ATCB
;
978 -- The common part between various tasking implementations
980 Entry_Calls
: Entry_Call_Array
;
981 -- An array of entry calls
983 -- Protection: The elements of this array are on entry call queues
984 -- associated with protected objects or task entries, and are protected
985 -- by the protected object lock or Acceptor.L, respectively.
987 New_Base_Priority
: System
.Any_Priority
;
988 -- New value for Base_Priority (for dynamic priorities package)
990 -- Protection: Self.L
992 Open_Accepts
: Accept_List_Access
;
993 -- This points to the Open_Accepts array of accept alternatives passed
994 -- to the RTS by the compiler-generated code to Selective_Wait. It is
995 -- non-null iff this task is ready to accept an entry call.
997 -- Protection: Self.L
999 Chosen_Index
: Select_Index
;
1000 -- The index in Open_Accepts of the entry call accepted by a selective
1001 -- wait executed by this task.
1003 -- Protection: Written by both Self and Caller. Usually protected by
1004 -- Self.L. However, once the selection is known to have been written it
1005 -- can be accessed without protection. This happens after Self has
1006 -- updated it itself using information from a suspended Caller, or
1007 -- after Caller has updated it and awakened Self.
1009 Master_Of_Task
: Master_Level
;
1010 -- The task executing the master of this task, and the ID of this task's
1011 -- master (unique only among masters currently active within Parent).
1013 -- Protection: Set by Activator before Self is activated, and read
1014 -- after Self is activated.
1016 Master_Within
: Master_Level
;
1017 -- The ID of the master currently executing within this task; that is,
1018 -- the most deeply nested currently active master.
1020 -- Protection: Only written by Self, and only read by Self or by
1021 -- dependents when Self is attempting to exit a master. Since Self will
1022 -- not write this field until the master is complete, the
1023 -- synchronization should be adequate to prevent races.
1025 Alive_Count
: Natural := 0;
1026 -- Number of tasks directly dependent on this task (including itself)
1027 -- that are still "alive", i.e. not terminated.
1029 -- Protection: Self.L
1031 Awake_Count
: Natural := 0;
1032 -- Number of tasks directly dependent on this task (including itself)
1033 -- still "awake", i.e., are not terminated and not waiting on a
1034 -- terminate alternative.
1036 -- Invariant: Awake_Count <= Alive_Count
1038 -- Protection: Self.L
1040 -- Beginning of flags
1042 Aborting
: Boolean := False;
1043 pragma Atomic
(Aborting
);
1044 -- Self is in the process of aborting. While set, prevents multiple
1045 -- abort signals from being sent by different aborter while abort
1046 -- is acted upon. This is essential since an aborter which calls
1047 -- Abort_To_Level could set the Pending_ATC_Level to yet a lower level
1048 -- (than the current level), may be preempted and would send the
1049 -- abort signal when resuming execution. At this point, the abortee
1050 -- may have completed abort to the proper level such that the
1051 -- signal (and resulting abort exception) are not handled any more.
1052 -- In other words, the flag prevents a race between multiple aborters
1054 -- Protection: protected by atomic access.
1056 ATC_Hack
: Boolean := False;
1057 pragma Atomic
(ATC_Hack
);
1059 -- Temporary fix, to allow Undefer_Abort to reset Aborting in the
1060 -- handler for Abort_Signal that encloses an async. entry call.
1061 -- For the longer term, this should be done via code in the
1064 Callable
: Boolean := True;
1065 -- It is OK to call entries of this task
1067 Dependents_Aborted
: Boolean := False;
1068 -- This is set to True by whichever task takes responsibility for
1069 -- aborting the dependents of this task.
1071 -- Protection: Self.L
1073 Interrupt_Entry
: Boolean := False;
1074 -- Indicates if one or more Interrupt Entries are attached to the task.
1075 -- This flag is needed for cleaning up the Interrupt Entry bindings.
1077 Pending_Action
: Boolean := False;
1078 -- Unified flag indicating some action needs to be take when abort
1079 -- next becomes undeferred. Currently set if:
1080 -- . Pending_Priority_Change is set
1081 -- . Pending_ATC_Level is changed
1082 -- . Requeue involving POs
1083 -- (Abortable field may have changed and the Wait_Until_Abortable
1084 -- has to recheck the abortable status of the call.)
1085 -- . Exception_To_Raise is non-null
1087 -- Protection: Self.L
1089 -- This should never be reset back to False outside of the procedure
1090 -- Do_Pending_Action, which is called by Undefer_Abort. It should only
1091 -- be set to True by Set_Priority and Abort_To_Level.
1093 Pending_Priority_Change
: Boolean := False;
1094 -- Flag to indicate pending priority change (for dynamic priorities
1095 -- package). The base priority is updated on the next abort
1096 -- completion point (aka. synchronization point).
1098 -- Protection: Self.L
1100 Terminate_Alternative
: Boolean := False;
1101 -- Task is accepting Select with Terminate Alternative
1103 -- Protection: Self.L
1107 -- Beginning of counts
1109 ATC_Nesting_Level
: ATC_Level
:= Level_No_ATC_Occurring
;
1110 -- The dynamic level of ATC nesting (currently executing nested
1111 -- asynchronous select statements) in this task.
1113 -- Protection: Self_ID.L. Only Self reads or updates this field.
1114 -- Decrementing it deallocates an Entry_Calls component, and care must
1115 -- be taken that all references to that component are eliminated before
1116 -- doing the decrement. This in turn will require locking a protected
1117 -- object (for a protected entry call) or the Acceptor's lock (for a
1118 -- task entry call). No other task should attempt to read or modify
1121 Deferral_Level
: Natural := 1;
1122 -- This is the number of times that Defer_Abort has been called by
1123 -- this task without a matching Undefer_Abort call. Abortion is only
1124 -- allowed when this zero. It is initially 1, to protect the task at
1127 -- Protection: Only updated by Self; access assumed to be atomic
1129 Pending_ATC_Level
: ATC_Level_Base
:= Level_No_Pending_Abort
;
1130 -- Indicates the ATC level to which this task is currently being
1131 -- aborted. Two special values exist:
1133 -- * Level_Completed_Task: the task has completed.
1135 -- * Level_No_Pending_Abort: the task is not being aborted to any
1138 -- All other values indicate the task has not completed. This should
1139 -- ONLY be modified by Abort_To_Level and Exit_One_ATC_Level.
1141 -- Protection: Self.L
1143 Serial_Number
: Task_Serial_Number
;
1144 -- Monotonic counter to provide some way to check locking rules/ordering
1146 Known_Tasks_Index
: Integer := -1;
1147 -- Index in the System.Tasking.Debug.Known_Tasks array
1149 User_State
: Long_Integer := 0;
1150 -- User-writeable location, for use in debugging tasks; also provides a
1151 -- simple task specific data.
1153 Free_On_Termination
: Boolean := False;
1154 -- Deallocate the ATCB when the task terminates. This flag is normally
1155 -- False, and is set True when Unchecked_Deallocation is called on a
1156 -- non-terminated task so that the associated storage is automatically
1157 -- reclaimed when the task terminates.
1159 Attributes
: Attribute_Array
:= [others => Null_Address
];
1162 -- IMPORTANT Note: the Entry_Queues field is last for efficiency of
1163 -- access to other fields, do not put new fields after this one.
1165 Entry_Queues
: Task_Entry_Queue_Array
(1 .. Entry_Num
);
1166 -- An array of task entry queues
1168 -- Protection: Self.L. Once a task has set Self.Stage to Completing, it
1169 -- has exclusive access to this field.
1170 end record; -- Ada_Task_Control_Block
1172 --------------------
1173 -- Initialization --
1174 --------------------
1176 procedure Initialize
;
1177 -- This procedure constitutes the first part of the initialization of the
1178 -- GNARL. This includes creating data structures to make the initial thread
1179 -- into the environment task. The last part of the initialization is done
1180 -- in System.Tasking.Initialization or System.Tasking.Restricted.Stages.
1181 -- All the initializations used to be in Tasking.Initialization, but this
1182 -- is no longer possible with the run time simplification (including
1183 -- optimized PO and the restricted run time) since one cannot rely on
1184 -- System.Tasking.Initialization being present, as was done before.
1186 procedure Initialize_ATCB
1188 Task_Entry_Point
: Task_Procedure_Access
;
1189 Task_Arg
: System
.Address
;
1191 Elaborated
: Access_Boolean
;
1192 Base_Priority
: System
.Any_Priority
;
1193 Base_CPU
: System
.Multiprocessors
.CPU_Range
;
1194 Domain
: Dispatching_Domain_Access
;
1195 Task_Info
: System
.Task_Info
.Task_Info_Type
;
1196 Stack_Size
: System
.Parameters
.Size_Type
;
1198 Success
: out Boolean);
1199 -- Initialize fields of the TCB for task T, and link into global TCB
1200 -- structures. Call this only with abort deferred and holding RTS_Lock.
1201 -- Self_ID is the calling task (normally the activator of T). Success is
1202 -- set to indicate whether the TCB was successfully initialized.
1206 Null_Task
: constant Task_Id
:= null;
1208 type Activation_Chain
is limited record
1212 -- Activation_Chain is an in-out parameter of initialization procedures and
1213 -- it must be passed by reference because the init proc may terminate
1214 -- abnormally after creating task components, and these must be properly
1215 -- registered for removal (Expunge_Unactivated_Tasks). The "limited" forces
1216 -- Activation_Chain to be a by-reference type; see RM-6.2(4).
1218 function Number_Of_Entries
(Self_Id
: Task_Id
) return Entry_Index
;
1219 -- Given a task, return the number of entries it contains