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-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, 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 -- Used for Exception_Id
41 -- Exception_Occurrence
43 with System
.Parameters
;
46 with System
.Task_Info
;
47 -- used for Task_Info_Type
49 with System
.Soft_Links
;
52 with System
.Task_Primitives
;
53 -- used for Private_Data
55 with System
.Stack_Usage
;
56 -- used for Stack_Analyzer
58 with Unchecked_Conversion
;
60 package System
.Tasking
is
67 -- The following rules must be followed at all times, to prevent
68 -- deadlock and generally ensure correct operation of locking.
70 -- Never lock a lock unless abort is deferred
72 -- Never undefer abort while holding a lock
74 -- Overlapping critical sections must be properly nested, and locks must
75 -- be released in LIFO order. e.g., the following is not allowed:
85 -- Locks with lower (smaller) level number cannot be locked
86 -- while holding a lock with a higher level number. (The level
88 -- 1. System.Tasking.PO_Simple.Protection.L (any PO lock)
89 -- 2. System.Tasking.Initialization.Global_Task_Lock (in body)
90 -- 3. System.Task_Primitives.Operations.Single_RTS_Lock
91 -- 4. System.Tasking.Ada_Task_Control_Block.LL.L (any TCB lock)
93 -- Clearly, there can be no circular chain of hold-and-wait
94 -- relationships involving locks in different ordering levels.
96 -- We used to have Global_Task_Lock before Protection.L but this was
97 -- clearly wrong since there can be calls to "new" inside protected
98 -- operations. The new ordering prevents these failures.
100 -- Sometimes we need to hold two ATCB locks at the same time. To allow us
101 -- to order the locking, each ATCB is given a unique serial number. If one
102 -- needs to hold locks on several ATCBs at once, the locks with lower
103 -- serial numbers must be locked first.
105 -- We don't always need to check the serial numbers, since the serial
106 -- numbers are assigned sequentially, and so:
108 -- . The parent of a task always has a lower serial number.
109 -- . The activator of a task always has a lower serial number.
110 -- . The environment task has a lower serial number than any other task.
111 -- . If the activator of a task is different from the task's parent,
112 -- the parent always has a lower serial number than the activator.
114 ---------------------------------
115 -- Task_Id related definitions --
116 ---------------------------------
118 type Ada_Task_Control_Block
;
120 type Task_Id
is access all Ada_Task_Control_Block
;
122 Null_Task
: constant Task_Id
;
124 type Task_List
is array (Positive range <>) of Task_Id
;
126 function Self
return Task_Id
;
127 pragma Inline
(Self
);
128 -- This is the compiler interface version of this function. Do not call
129 -- from the run-time system.
131 function To_Task_Id
is new Unchecked_Conversion
(System
.Address
, Task_Id
);
132 function To_Address
is new Unchecked_Conversion
(Task_Id
, System
.Address
);
134 -----------------------
135 -- Enumeration types --
136 -----------------------
140 -- Task has been created but has not been activated.
141 -- It cannot be executing.
144 -- For all states from here down, the task has been activated.
145 -- For all states from here down, except for Terminated, the task
147 -- Activator = null iff it has not yet completed activating.
149 -- For all states from here down,
150 -- the task has been activated, and may be executing.
153 -- Task is not blocked for any reason known to Ada.
154 -- (It may be waiting for a mutex, though.)
155 -- It is conceptually "executing" in normal mode.
158 -- The task is terminated, in the sense of ARM 9.3 (5).
159 -- Any dependents that were waiting on terminate
160 -- alternatives have been awakened and have terminated themselves.
163 -- Task is waiting for created tasks to complete activation
166 -- Task is waiting on an accept or selective wait statement
169 -- Task is waiting on an entry call
172 -- Task is waiting to start the abortable part of an
173 -- asynchronous select statement.
176 -- Task is waiting on a select statement with only a delay
179 Master_Completion_Sleep
,
180 -- Master completion has two phases.
181 -- In Phase 1 the task is sleeping in Complete_Master
182 -- having completed a master within itself,
183 -- and is waiting for the tasks dependent on that master to become
184 -- terminated or waiting on a terminate Phase.
186 Master_Phase_2_Sleep
,
187 -- In Phase 2 the task is sleeping in Complete_Master
188 -- waiting for tasks on terminate alternatives to finish
191 -- The following are special uses of sleep, for server tasks
192 -- within the run-time system.
194 Interrupt_Server_Idle_Sleep
,
195 Interrupt_Server_Blocked_Interrupt_Sleep
,
200 -- The task has been held by Asynchronous_Task_Control.Hold_Task
202 Interrupt_Server_Blocked_On_Event_Flag
203 -- The task has been blocked on a system call waiting for the
208 (Simple_Call
, Conditional_Call
, Asynchronous_Call
, Timed_Call
);
210 type Select_Modes
is (Simple_Mode
, Else_Mode
, Terminate_Mode
, Delay_Mode
);
212 subtype Delay_Modes
is Integer;
214 -------------------------------
215 -- Entry related definitions --
216 -------------------------------
218 Null_Entry
: constant := 0;
220 Max_Entry
: constant := Integer'Last;
222 Interrupt_Entry
: constant := -2;
224 Cancelled_Entry
: constant := -1;
226 type Entry_Index
is range Interrupt_Entry
.. Max_Entry
;
228 Null_Task_Entry
: constant := Null_Entry
;
230 Max_Task_Entry
: constant := Max_Entry
;
232 type Task_Entry_Index
is new Entry_Index
233 range Null_Task_Entry
.. Max_Task_Entry
;
235 type Entry_Call_Record
;
237 type Entry_Call_Link
is access all Entry_Call_Record
;
239 type Entry_Queue
is record
240 Head
: Entry_Call_Link
;
241 Tail
: Entry_Call_Link
;
244 type Task_Entry_Queue_Array
is
245 array (Task_Entry_Index
range <>) of Entry_Queue
;
247 ----------------------------------
248 -- Entry_Call_Record definition --
249 ----------------------------------
251 type Entry_Call_State
is
253 -- the call is not abortable, and never can be
256 -- the call is not abortable, but may become so
259 -- the call is not abortable, but once was
262 -- the call is abortable
265 -- the call has been completed
268 -- the call was asynchronous, and was cancelled
271 -- Never_Abortable is used for calls that are made in a abort
272 -- deferred region (see ARM 9.8(5-11), 9.8 (20)).
273 -- Such a call is never abortable.
275 -- The Was_ vs. Not_Yet_ distinction is needed to decide whether it
276 -- is OK to advance into the abortable part of an async. select stmt.
277 -- That is allowed iff the mode is Now_ or Was_.
279 -- Done indicates the call has been completed, without cancellation,
280 -- or no call has been made yet at this ATC nesting level,
281 -- and so aborting the call is no longer an issue.
282 -- Completion of the call does not necessarily indicate "success";
283 -- the call may be returning an exception if Exception_To_Raise is
286 -- Cancelled indicates the call was cancelled,
287 -- and so aborting the call is no longer an issue.
289 -- The call is on an entry queue unless
290 -- State >= Done, in which case it may or may not be still Onqueue.
292 -- Please do not modify the order of the values, without checking
293 -- all uses of this type. We rely on partial "monotonicity" of
294 -- Entry_Call_Record.State to avoid locking when we access this
295 -- value for certain tests. In particular:
297 -- 1) Once State >= Done, we can rely that the call has been
298 -- completed. If State >= Done, it will not
299 -- change until the task does another entry call at this level.
301 -- 2) Once State >= Was_Abortable, we can rely that the call has
302 -- been queued abortably at least once, and so the check for
303 -- whether it is OK to advance to the abortable part of an
304 -- async. select statement does not need to lock anything.
306 type Restricted_Entry_Call_Record
is record
312 State
: Entry_Call_State
;
313 pragma Atomic
(State
);
314 -- Indicates part of the state of the call.
316 -- Protection: If the call is not on a queue, it should only be
317 -- accessed by Self, and Self does not need any lock to modify this
320 -- Once the call is on a queue, the value should be something other
321 -- than Done unless it is cancelled, and access is controller by the
322 -- "server" of the queue -- i.e., the lock of Checked_To_Protection
323 -- (Call_Target) if the call record is on the queue of a PO, or the
324 -- lock of Called_Target if the call is on the queue of a task. See
325 -- comments on type declaration for more details.
327 Uninterpreted_Data
: System
.Address
;
328 -- Data passed by the compiler
330 Exception_To_Raise
: Ada
.Exceptions
.Exception_Id
;
331 -- The exception to raise once this call has been completed without
334 pragma Suppress_Initialization
(Restricted_Entry_Call_Record
);
336 -------------------------------------------
337 -- Task termination procedure definition --
338 -------------------------------------------
340 -- We need to redefine here these types (already defined in
341 -- Ada.Task_Termination) for avoiding circular dependencies.
343 type Cause_Of_Termination
is (Normal
, Abnormal
, Unhandled_Exception
);
344 -- Possible causes for task termination:
346 -- Normal means that the task terminates due to completing the
347 -- last sentence of its body, or as a result of waiting on a
348 -- terminate alternative.
350 -- Abnormal means that the task terminates because it is being aborted
352 -- handled_Exception means that the task terminates because of exception
353 -- raised by by the execution of its task_body.
355 type Termination_Handler
is access protected procedure
356 (Cause
: in Cause_Of_Termination
;
358 X
: in Ada
.Exceptions
.Exception_Occurrence
);
359 -- Used to represent protected procedures to be executed when task
362 ------------------------------------
363 -- Task related other definitions --
364 ------------------------------------
366 type Activation_Chain
is limited private;
367 -- Comment required ???
369 type Activation_Chain_Access
is access all Activation_Chain
;
370 -- Comment required ???
372 type Task_Procedure_Access
is access procedure (Arg
: System
.Address
);
374 type Access_Boolean
is access all Boolean;
376 function Detect_Blocking
return Boolean;
377 pragma Inline
(Detect_Blocking
);
378 -- Return whether the Detect_Blocking pragma is enabled.
380 ----------------------------------------------
381 -- Ada_Task_Control_Block (ATCB) definition --
382 ----------------------------------------------
384 -- Notes on protection (synchronization) of TRTS data structures
386 -- Any field of the TCB can be written by the activator of a task when the
387 -- task is created, since no other task can access the new task's
388 -- state until creation is complete.
390 -- The protection for each field is described in a comment starting with
393 -- When a lock is used to protect an ATCB field, this lock is simply named
395 -- Some protection is described in terms of tasks related to the
396 -- ATCB being protected. These are:
398 -- Self: The task which is controlled by this ATCB
399 -- Acceptor: A task accepting a call from Self
400 -- Caller: A task calling an entry of Self
401 -- Parent: The task executing the master on which Self depends
402 -- Dependent: A task dependent on Self
403 -- Activator: The task that created Self and initiated its activation
404 -- Created: A task created and activated by Self
406 -- Note: The order of the fields is important to implement efficiently
407 -- tasking support under gdb.
408 -- Currently gdb relies on the order of the State, Parent, Base_Priority,
409 -- Task_Image, Task_Image_Len, Call and LL fields.
411 -------------------------
412 -- Common ATCB section --
413 -------------------------
415 -- Section used by all GNARL implementations (regular and restricted)
417 type Common_ATCB
is record
419 pragma Atomic
(State
);
420 -- Encodes some basic information about the state of a task,
421 -- including whether it has been activated, whether it is sleeping,
422 -- and whether it is terminated.
424 -- Protection: Self.L
427 -- The task on which this task depends.
428 -- See also Master_Level and Master_Within.
430 Base_Priority
: System
.Any_Priority
;
431 -- Base priority, not changed during entry calls, only changed
432 -- via dynamic priorities package.
434 -- Protection: Only written by Self, accessed by anyone
436 Current_Priority
: System
.Any_Priority
;
437 -- Active priority, except that the effects of protected object
438 -- priority ceilings are not reflected. This only reflects explicit
439 -- priority changes and priority inherited through task activation
442 -- Ada 95 notes: In Ada 95, this field will be transferred to the
443 -- Priority field of an Entry_Calls component when an entry call
444 -- is initiated. The Priority of the Entry_Calls component will not
445 -- change for the duration of the call. The accepting task can
446 -- use it to boost its own priority without fear of its changing in
449 -- This can safely be used in the priority ordering
450 -- of entry queues. Once a call is queued, its priority does not
453 -- Since an entry call cannot be made while executing
454 -- a protected action, the priority of a task will never reflect a
455 -- priority ceiling change at the point of an entry call.
457 -- Protection: Only written by Self, and only accessed when Acceptor
458 -- accepts an entry or when Created activates, at which points Self is
461 Protected_Action_Nesting
: Natural;
462 pragma Atomic
(Protected_Action_Nesting
);
463 -- The dynamic level of protected action nesting for this task. This
464 -- field is needed for checking whether potentially blocking operations
465 -- are invoked from protected actions. pragma Atomic is used because it
466 -- can be read/written from protected interrupt handlers.
468 Task_Image
: String (1 .. 32);
469 -- Hold a string that provides a readable id for task,
470 -- built from the variable of which it is a value or component.
472 Task_Image_Len
: Natural;
473 -- Actual length of Task_Image
475 Call
: Entry_Call_Link
;
476 -- The entry call that has been accepted by this task.
478 -- Protection: Self.L. Self will modify this field when Self.Accepting
479 -- is False, and will not need the mutex to do so. Once a task sets
480 -- Pending_ATC_Level = 0, no other task can access this field.
482 LL
: aliased Task_Primitives
.Private_Data
;
483 -- Control block used by the underlying low-level tasking service
486 -- Protection: This is used only by the GNULLI implementation, which
487 -- takes care of all of its synchronization.
489 Task_Arg
: System
.Address
;
490 -- The argument to task procedure. Provide a handle for discriminant
493 -- Protection: Part of the synchronization between Self and Activator.
494 -- Activator writes it, once, before Self starts executing. Thereafter,
495 -- Self only reads it.
497 Task_Entry_Point
: Task_Procedure_Access
;
498 -- Information needed to call the procedure containing the code for
499 -- the body of this task.
501 -- Protection: Part of the synchronization between Self and Activator.
502 -- Activator writes it, once, before Self starts executing. Self reads
503 -- it, once, as part of its execution.
505 Compiler_Data
: System
.Soft_Links
.TSD
;
506 -- Task-specific data needed by the compiler to store per-task
509 -- Protection: Only accessed by Self
511 All_Tasks_Link
: Task_Id
;
512 -- Used to link this task to the list of all tasks in the system
514 -- Protection: RTS_Lock
516 Activation_Link
: Task_Id
;
517 -- Used to link this task to a list of tasks to be activated
519 -- Protection: Only used by Activator
522 -- The task that created this task, either by declaring it as a task
523 -- object or by executing a task allocator. The value is null iff Self
524 -- has completed activation.
526 -- Protection: Set by Activator before Self is activated, and only read
527 -- and modified by Self after that.
529 Wait_Count
: Integer;
530 -- This count is used by a task that is waiting for other tasks. At all
531 -- other times, the value should be zero. It is used differently in
532 -- several different states. Since a task cannot be in more than one of
533 -- these states at the same time, a single counter suffices.
535 -- Protection: Self.L
539 -- This is the number of tasks that this task is activating, i.e. the
540 -- children that have started activation but have not completed it.
542 -- Protection: Self.L and Created.L. Both mutexes must be locked, since
543 -- Self.Activation_Count and Created.State must be synchronized.
545 -- Master_Completion_Sleep (phase 1)
547 -- This is the number dependent tasks of a master being completed by
548 -- Self that are not activated, not terminated, and not waiting on a
549 -- terminate alternative.
551 -- Master_Completion_2_Sleep (phase 2)
553 -- This is the count of tasks dependent on a master being completed by
554 -- Self which are waiting on a terminate alternative.
556 Elaborated
: Access_Boolean
;
557 -- Pointer to a flag indicating that this task's body has been
558 -- elaborated. The flag is created and managed by the
559 -- compiler-generated code.
561 -- Protection: The field itself is only accessed by Activator. The flag
562 -- that it points to is updated by Master and read by Activator; access
563 -- is assumed to be atomic.
565 Activation_Failed
: Boolean;
566 -- Set to True if activation of a chain of tasks fails,
567 -- so that the activator should raise Tasking_Error.
569 Task_Info
: System
.Task_Info
.Task_Info_Type
;
570 -- System-specific attributes of the task as specified by the
573 Analyzer
: System
.Stack_Usage
.Stack_Analyzer
;
574 -- For storing informations used to measure the stack usage.
576 Global_Task_Lock_Nesting
: Natural;
577 -- This is the current nesting level of calls to
578 -- System.Tasking.Initialization.Lock_Task. This allows a task to call
579 -- Lock_Task multiple times without deadlocking. A task only locks
580 -- Global_Task_Lock when its Global_Task_Lock_Nesting goes from 0 to 1,
581 -- and only unlocked when it goes from 1 to 0.
583 -- Protection: Only accessed by Self
585 Fall_Back_Handler
: Termination_Handler
;
586 pragma Atomic
(Fall_Back_Handler
);
587 -- This is the fall-back handler that applies to the dependent tasks of
590 -- Protection: atomic access
592 Specific_Handler
: Termination_Handler
;
593 pragma Atomic
(Specific_Handler
);
594 -- This is the specific handler that applies only to this task, and not
595 -- any of its dependent tasks.
597 -- Protection: atomic access
600 ---------------------------------------
601 -- Restricted_Ada_Task_Control_Block --
602 ---------------------------------------
604 -- This type should only be used by the restricted GNARLI and by
605 -- restricted GNULL implementations to allocate an ATCB (see
606 -- System.Task_Primitives.Operations.New_ATCB) that will take
607 -- significantly less memory.
609 -- Note that the restricted GNARLI should only access fields that are
610 -- present in the Restricted_Ada_Task_Control_Block structure.
612 type Restricted_Ada_Task_Control_Block
(Entry_Num
: Task_Entry_Index
) is
614 Common
: Common_ATCB
;
615 -- The common part between various tasking implementations
617 Entry_Call
: aliased Restricted_Entry_Call_Record
;
618 -- Protection: This field is used on entry call "queues" associated
619 -- with protected objects, and is protected by the protected object
622 pragma Suppress_Initialization
(Restricted_Ada_Task_Control_Block
);
624 Interrupt_Manager_ID
: Task_Id
;
625 -- This task ID is declared here to break circular dependencies.
626 -- Also declare Interrupt_Manager_ID after Task_Id is known, to avoid
627 -- generating unneeded finalization code.
629 -----------------------
630 -- List of all Tasks --
631 -----------------------
633 All_Tasks_List
: Task_Id
;
634 -- Global linked list of all tasks
636 ------------------------------------------
637 -- Regular (non restricted) definitions --
638 ------------------------------------------
640 --------------------------------
641 -- Master Related Definitions --
642 --------------------------------
644 subtype Master_Level
is Integer;
645 subtype Master_ID
is Master_Level
;
647 -- Normally, a task starts out with internal master nesting level one
648 -- larger than external master nesting level. It is incremented to one by
649 -- Enter_Master, which is called in the task body only if the compiler
650 -- thinks the task may have dependent tasks. It is set to for the
651 -- environment task, the level 2 is reserved for server tasks of the
652 -- run-time system (the so called "independent tasks"), and the level 3 is
653 -- for the library level tasks.
655 Environment_Task_Level
: constant Master_Level
:= 1;
656 Independent_Task_Level
: constant Master_Level
:= 2;
657 Library_Task_Level
: constant Master_Level
:= 3;
659 ------------------------------
660 -- Task size, priority info --
661 ------------------------------
663 Unspecified_Priority
: constant Integer := System
.Priority
'First - 1;
665 Priority_Not_Boosted
: constant Integer := System
.Priority
'First - 1;
666 -- Definition of Priority actually has to come from the RTS configuration
668 subtype Rendezvous_Priority
is Integer
669 range Priority_Not_Boosted
.. System
.Any_Priority
'Last;
671 ------------------------------------
672 -- Rendezvous related definitions --
673 ------------------------------------
675 No_Rendezvous
: constant := 0;
677 Max_Select
: constant Integer := Integer'Last;
680 subtype Select_Index
is Integer range No_Rendezvous
.. Max_Select
;
681 -- type Select_Index is range No_Rendezvous .. Max_Select;
683 subtype Positive_Select_Index
is
684 Select_Index
range 1 .. Select_Index
'Last;
686 type Accept_Alternative
is record
688 S
: Task_Entry_Index
;
692 array (Positive_Select_Index
range <>) of Accept_Alternative
;
694 type Accept_List_Access
is access constant Accept_List
;
696 -----------------------------------
697 -- ATC_Level related definitions --
698 -----------------------------------
700 Max_ATC_Nesting
: constant Natural := 20;
702 subtype ATC_Level_Base
is Integer range 0 .. Max_ATC_Nesting
;
704 ATC_Level_Infinity
: constant ATC_Level_Base
:= ATC_Level_Base
'Last;
706 subtype ATC_Level
is ATC_Level_Base
range 0 .. ATC_Level_Base
'Last - 1;
708 subtype ATC_Level_Index
is ATC_Level
range 1 .. ATC_Level
'Last;
710 ----------------------------------
711 -- Entry_Call_Record definition --
712 ----------------------------------
714 type Entry_Call_Record
is record
720 State
: Entry_Call_State
;
721 pragma Atomic
(State
);
722 -- Indicates part of the state of the call
724 -- Protection: If the call is not on a queue, it should only be
725 -- accessed by Self, and Self does not need any lock to modify this
726 -- field. Once the call is on a queue, the value should be something
727 -- other than Done unless it is cancelled, and access is controller by
728 -- the "server" of the queue -- i.e., the lock of Checked_To_Protection
729 -- (Call_Target) if the call record is on the queue of a PO, or the
730 -- lock of Called_Target if the call is on the queue of a task. See
731 -- comments on type declaration for more details.
733 Uninterpreted_Data
: System
.Address
;
734 -- Data passed by the compiler
736 Exception_To_Raise
: Ada
.Exceptions
.Exception_Id
;
737 -- The exception to raise once this call has been completed without
740 Prev
: Entry_Call_Link
;
742 Next
: Entry_Call_Link
;
745 -- One of Self and Level are redundant in this implementation, since
746 -- each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must
747 -- have access to the entry call record to be reading this, we could
748 -- get Self from Level, or Level from Self. However, this requires
749 -- non-portable address arithmetic.
753 Prio
: System
.Any_Priority
;
755 -- The above fields are those that there may be some hope of packing.
756 -- They are gathered together to allow for compilers that lay records
757 -- out contiguously, to allow for such packing.
759 Called_Task
: Task_Id
;
760 pragma Atomic
(Called_Task
);
761 -- Use for task entry calls. The value is null if the call record is
762 -- not in use. Conversely, unless State is Done and Onqueue is false,
763 -- Called_Task points to an ATCB.
765 -- Protection: Called_Task.L
767 Called_PO
: System
.Address
;
768 pragma Atomic
(Called_PO
);
769 -- Similar to Called_Task but for protected objects
771 -- Note that the previous implementation tried to merge both
772 -- Called_Task and Called_PO but this ended up in many unexpected
773 -- complications (e.g having to add a magic number in the ATCB, which
774 -- caused gdb lots of confusion) with no real gain since the
775 -- Lock_Server implementation still need to loop around chasing for
776 -- pointer changes even with a single pointer.
778 Acceptor_Prev_Call
: Entry_Call_Link
;
779 -- For task entry calls only
781 Acceptor_Prev_Priority
: Rendezvous_Priority
:= Priority_Not_Boosted
;
782 -- For task entry calls only. The priority of the most recent prior
783 -- call being serviced. For protected entry calls, this function should
784 -- be performed by GNULLI ceiling locking.
786 Cancellation_Attempted
: Boolean := False;
787 pragma Atomic
(Cancellation_Attempted
);
788 -- Cancellation of the call has been attempted.
789 -- Consider merging this into State???
791 Requeue_With_Abort
: Boolean := False;
792 -- Temporary to tell caller whether requeue is with abort.
793 -- Find a better way of doing this ???
795 Needs_Requeue
: Boolean := False;
796 -- Temporary to tell acceptor of task entry call that
797 -- Exceptional_Complete_Rendezvous needs to do requeue.
800 ------------------------------------
801 -- Task related other definitions --
802 ------------------------------------
804 type Access_Address
is access all System
.Address
;
805 -- Comment on what this is used for ???
807 pragma No_Strict_Aliasing
(Access_Address
);
808 -- This type is used in contexts where aliasing may be an issue (see
809 -- for example s-tataat.adb), so we avoid any incorrect aliasing
812 ----------------------------------------------
813 -- Ada_Task_Control_Block (ATCB) definition --
814 ----------------------------------------------
816 type Entry_Call_Array
is array (ATC_Level_Index
) of
817 aliased Entry_Call_Record
;
819 type Direct_Index
is range 0 .. Parameters
.Default_Attribute_Count
;
820 subtype Direct_Index_Range
is Direct_Index
range 1 .. Direct_Index
'Last;
821 -- Attributes with indices in this range are stored directly in the task
822 -- control block. Such attributes must be Address-sized. Other attributes
823 -- will be held in dynamically allocated records chained off of the task
826 type Direct_Attribute_Element
is mod Memory_Size
;
827 pragma Atomic
(Direct_Attribute_Element
);
829 type Direct_Attribute_Array
is
830 array (Direct_Index_Range
) of aliased Direct_Attribute_Element
;
832 type Direct_Index_Vector
is mod 2 ** Parameters
.Default_Attribute_Count
;
833 -- This is a bit-vector type, used to store information about
834 -- the usage of the direct attribute fields.
836 type Task_Serial_Number
is mod 2 ** 64;
837 -- Used to give each task a unique serial number
839 type Ada_Task_Control_Block
(Entry_Num
: Task_Entry_Index
) is record
840 Common
: Common_ATCB
;
841 -- The common part between various tasking implementations
843 Entry_Calls
: Entry_Call_Array
;
844 -- An array of entry calls
846 -- Protection: The elements of this array are on entry call queues
847 -- associated with protected objects or task entries, and are protected
848 -- by the protected object lock or Acceptor.L, respectively.
850 New_Base_Priority
: System
.Any_Priority
;
851 -- New value for Base_Priority (for dynamic priorities package)
853 -- Protection: Self.L
855 Open_Accepts
: Accept_List_Access
;
856 -- This points to the Open_Accepts array of accept alternatives passed
857 -- to the RTS by the compiler-generated code to Selective_Wait. It is
858 -- non-null iff this task is ready to accept an entry call.
860 -- Protection: Self.L
862 Chosen_Index
: Select_Index
;
863 -- The index in Open_Accepts of the entry call accepted by a selective
864 -- wait executed by this task.
866 -- Protection: Written by both Self and Caller. Usually protected by
867 -- Self.L. However, once the selection is known to have been written it
868 -- can be accessed without protection. This happens after Self has
869 -- updated it itself using information from a suspended Caller, or
870 -- after Caller has updated it and awakened Self.
872 Master_of_Task
: Master_Level
;
873 -- The task executing the master of this task, and the ID of this task's
874 -- master (unique only among masters currently active within Parent).
876 -- Protection: Set by Activator before Self is activated, and read
877 -- after Self is activated.
879 Master_Within
: Master_Level
;
880 -- The ID of the master currently executing within this task; that is,
881 -- the most deeply nested currently active master.
883 -- Protection: Only written by Self, and only read by Self or by
884 -- dependents when Self is attempting to exit a master. Since Self will
885 -- not write this field until the master is complete, the
886 -- synchronization should be adequate to prevent races.
888 Alive_Count
: Integer := 0;
889 -- Number of tasks directly dependent on this task (including itself)
890 -- that are still "alive", i.e. not terminated.
892 -- Protection: Self.L
894 Awake_Count
: Integer := 0;
895 -- Number of tasks directly dependent on this task (including itself)
896 -- still "awake", i.e., are not terminated and not waiting on a
897 -- terminate alternative.
899 -- Invariant: Awake_Count <= Alive_Count
901 -- Protection: Self.L
903 -- Beginning of flags
905 Aborting
: Boolean := False;
906 pragma Atomic
(Aborting
);
907 -- Self is in the process of aborting. While set, prevents multiple
908 -- abort signals from being sent by different aborter while abort
909 -- is acted upon. This is essential since an aborter which calls
910 -- Abort_To_Level could set the Pending_ATC_Level to yet a lower level
911 -- (than the current level), may be preempted and would send the
912 -- abort signal when resuming execution. At this point, the abortee
913 -- may have completed abort to the proper level such that the
914 -- signal (and resulting abort exception) are not handled any more.
915 -- In other words, the flag prevents a race between multiple aborters
917 -- Protection: protected by atomic access.
919 ATC_Hack
: Boolean := False;
920 pragma Atomic
(ATC_Hack
);
922 -- Temporary fix, to allow Undefer_Abort to reset Aborting in the
923 -- handler for Abort_Signal that encloses an async. entry call.
924 -- For the longer term, this should be done via code in the
927 Callable
: Boolean := True;
928 -- It is OK to call entries of this task
930 Dependents_Aborted
: Boolean := False;
931 -- This is set to True by whichever task takes responsibility for
932 -- aborting the dependents of this task.
934 -- Protection: Self.L
936 Interrupt_Entry
: Boolean := False;
937 -- Indicates if one or more Interrupt Entries are attached to the task.
938 -- This flag is needed for cleaning up the Interrupt Entry bindings.
940 Pending_Action
: Boolean := False;
941 -- Unified flag indicating some action needs to be take when abort
942 -- next becomes undeferred. Currently set if:
943 -- . Pending_Priority_Change is set
944 -- . Pending_ATC_Level is changed
945 -- . Requeue involving POs
946 -- (Abortable field may have changed and the Wait_Until_Abortable
947 -- has to recheck the abortable status of the call.)
948 -- . Exception_To_Raise is non-null
950 -- Protection: Self.L
952 -- This should never be reset back to False outside of the procedure
953 -- Do_Pending_Action, which is called by Undefer_Abort. It should only
954 -- be set to True by Set_Priority and Abort_To_Level.
956 Pending_Priority_Change
: Boolean := False;
957 -- Flag to indicate pending priority change (for dynamic priorities
958 -- package). The base priority is updated on the next abort
959 -- completion point (aka. synchronization point).
961 -- Protection: Self.L
963 Terminate_Alternative
: Boolean := False;
964 -- Task is accepting Select with Terminate Alternative
966 -- Protection: Self.L
970 -- Beginning of counts
972 ATC_Nesting_Level
: ATC_Level
:= 1;
973 -- The dynamic level of ATC nesting (currently executing nested
974 -- asynchronous select statements) in this task.
976 -- Protection: Self_ID.L. Only Self reads or updates this field.
977 -- Decrementing it deallocates an Entry_Calls component, and care must
978 -- be taken that all references to that component are eliminated before
979 -- doing the decrement. This in turn will require locking a protected
980 -- object (for a protected entry call) or the Acceptor's lock (for a
981 -- task entry call). No other task should attempt to read or modify
984 Deferral_Level
: Natural := 1;
985 -- This is the number of times that Defer_Abortion has been called by
986 -- this task without a matching Undefer_Abortion call. Abortion is only
987 -- allowed when this zero. It is initially 1, to protect the task at
990 -- Protection: Only updated by Self; access assumed to be atomic
992 Pending_ATC_Level
: ATC_Level_Base
:= ATC_Level_Infinity
;
993 -- The ATC level to which this task is currently being aborted. If the
994 -- value is zero, the entire task has "completed". That may be via
995 -- abort, exception propagation, or normal exit. If the value is
996 -- ATC_Level_Infinity, the task is not being aborted to any level. If
997 -- the value is positive, the task has not completed. This should ONLY
998 -- be modified by Abort_To_Level and Exit_One_ATC_Level.
1000 -- Protection: Self.L
1002 Serial_Number
: Task_Serial_Number
;
1003 -- A growing number to provide some way to check locking rules/ordering
1005 Known_Tasks_Index
: Integer := -1;
1006 -- Index in the System.Tasking.Debug.Known_Tasks array
1008 User_State
: Long_Integer := 0;
1009 -- User-writeable location, for use in debugging tasks; also provides a
1010 -- simple task specific data.
1012 Direct_Attributes
: Direct_Attribute_Array
;
1013 -- For task attributes that have same size as Address
1015 Is_Defined
: Direct_Index_Vector
:= 0;
1016 -- Bit I is 1 iff Direct_Attributes (I) is defined
1018 Indirect_Attributes
: Access_Address
;
1019 -- A pointer to chain of records for other attributes that are not
1020 -- address-sized, including all tagged types.
1022 Entry_Queues
: Task_Entry_Queue_Array
(1 .. Entry_Num
);
1023 -- An array of task entry queues
1025 -- Protection: Self.L. Once a task has set Self.Stage to Completing, it
1026 -- has exclusive access to this field.
1029 --------------------
1030 -- Initialization --
1031 --------------------
1033 procedure Initialize
;
1034 -- This procedure constitutes the first part of the initialization of the
1035 -- GNARL. This includes creating data structures to make the initial thread
1036 -- into the environment task. The last part of the initialization is done
1037 -- in System.Tasking.Initialization or System.Tasking.Restricted.Stages.
1038 -- All the initializations used to be in Tasking.Initialization, but this
1039 -- is no longer possible with the run time simplification (including
1040 -- optimized PO and the restricted run time) since one cannot rely on
1041 -- System.Tasking.Initialization being present, as was done before.
1043 procedure Initialize_ATCB
1045 Task_Entry_Point
: Task_Procedure_Access
;
1046 Task_Arg
: System
.Address
;
1048 Elaborated
: Access_Boolean
;
1049 Base_Priority
: System
.Any_Priority
;
1050 Task_Info
: System
.Task_Info
.Task_Info_Type
;
1051 Stack_Size
: System
.Parameters
.Size_Type
;
1053 Success
: out Boolean);
1054 -- Initialize fields of a TCB and link into global TCB structures Call
1055 -- this only with abort deferred and holding RTS_Lock. Need more
1056 -- documentation, mention T, and describe Success ???
1059 Null_Task
: constant Task_Id
:= null;
1061 type Activation_Chain
is record
1064 pragma Volatile
(Activation_Chain
);
1066 -- Activation_chain is an in-out parameter of initialization procedures
1067 -- and it must be passed by reference because the init proc may terminate
1068 -- abnormally after creating task components, and these must be properly
1069 -- registered for removal (Expunge_Unactivated_Tasks).