1------------------------------------------------------------------------------
2--                                                                          --
3--                  GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS                --
4--                                                                          --
5--                        S Y S T E M . T A S K I N G                       --
6--                                                                          --
7--                                  S p e c                                 --
8--                                                                          --
9--          Copyright (C) 1992-2014, Free Software Foundation, Inc.         --
10--                                                                          --
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.                                     --
17--                                                                          --
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.               --
21--                                                                          --
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/>.                                          --
26--                                                                          --
27-- GNARL was developed by the GNARL team at Florida State University.       --
28-- Extensive contributions were provided by Ada Core Technologies, Inc.     --
29--                                                                          --
30------------------------------------------------------------------------------
31
32--  This package provides necessary type definitions for compiler interface
33
34--  Note: the compiler generates direct calls to this interface, via Rtsfind.
35--  Any changes to this interface may require corresponding compiler changes.
36
37with Ada.Exceptions;
38with Ada.Unchecked_Conversion;
39
40with System.Parameters;
41with System.Task_Info;
42with System.Soft_Links;
43with System.Task_Primitives;
44with System.Stack_Usage;
45with System.Multiprocessors;
46
47package System.Tasking is
48   pragma Preelaborate;
49
50   -------------------
51   -- Locking Rules --
52   -------------------
53
54   --  The following rules must be followed at all times, to prevent
55   --  deadlock and generally ensure correct operation of locking.
56
57   --  Never lock a lock unless abort is deferred
58
59   --  Never undefer abort while holding a lock
60
61   --  Overlapping critical sections must be properly nested, and locks must
62   --  be released in LIFO order. E.g., the following is not allowed:
63
64   --         Lock (X);
65   --         ...
66   --         Lock (Y);
67   --         ...
68   --         Unlock (X);
69   --         ...
70   --         Unlock (Y);
71
72   --  Locks with lower (smaller) level number cannot be locked
73   --  while holding a lock with a higher level number. (The level
74
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)
79
80   --  Clearly, there can be no circular chain of hold-and-wait
81   --  relationships involving locks in different ordering levels.
82
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.
86
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
92   --  and deadlocks.
93
94   --  We don't always need to check the serial numbers, since the serial
95   --  numbers are assigned sequentially, and so:
96
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.
102
103   ---------------------------------
104   -- Task_Id related definitions --
105   ---------------------------------
106
107   type Ada_Task_Control_Block;
108
109   type Task_Id is access all Ada_Task_Control_Block;
110   for Task_Id'Size use System.Task_Primitives.Task_Address_Size;
111
112   Null_Task : constant Task_Id;
113
114   type Task_List is array (Positive range <>) of Task_Id;
115
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.
120
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);
127
128   -----------------------
129   -- Enumeration types --
130   -----------------------
131
132   type Task_States is
133     (Unactivated,
134      --  TCB initialized but not task has not been created.
135      --  It cannot be executing.
136
137--    Activating,
138--    --  ??? Temporarily at end of list for GDB compatibility
139--    --  Task has been created and is being made Runnable.
140
141      --  Active states
142      --  For all states from here down, the task has been activated.
143      --  For all states from here down, except for Terminated, the task
144      --  may be executing.
145      --  Activator = null iff it has not yet completed activating.
146
147      Runnable,
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.
151
152      Terminated,
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.
156
157      Activator_Sleep,
158      --  Task is waiting for created tasks to complete activation
159
160      Acceptor_Sleep,
161      --  Task is waiting on an accept or select with terminate
162
163--    Acceptor_Delay_Sleep,
164--    --  ??? Temporarily at end of list for GDB compatibility
165--    --  Task is waiting on an selective wait statement
166
167      Entry_Caller_Sleep,
168      --  Task is waiting on an entry call
169
170      Async_Select_Sleep,
171      --  Task is waiting to start the abortable part of an
172      --  asynchronous select statement.
173
174      Delay_Sleep,
175      --  Task is waiting on a select statement with only a delay
176      --  alternative open.
177
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.
184
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
188      --  terminating.
189
190      --  The following are special uses of sleep, for server tasks
191      --  within the run-time system.
192
193      Interrupt_Server_Idle_Sleep,
194      Interrupt_Server_Blocked_Interrupt_Sleep,
195      Timer_Server_Sleep,
196      AST_Server_Sleep,
197
198      Asynchronous_Hold,
199      --  The task has been held by Asynchronous_Task_Control.Hold_Task
200
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.
204
205      Activating,
206      --  Task has been created and is being made Runnable
207
208      Acceptor_Delay_Sleep
209      --  Task is waiting on an selective wait statement
210     );
211
212   type Call_Modes is
213     (Simple_Call, Conditional_Call, Asynchronous_Call, Timed_Call);
214
215   type Select_Modes is (Simple_Mode, Else_Mode, Terminate_Mode, Delay_Mode);
216
217   subtype Delay_Modes is Integer;
218
219   -------------------------------
220   -- Entry related definitions --
221   -------------------------------
222
223   Null_Entry : constant := 0;
224
225   Max_Entry : constant := Integer'Last;
226
227   Interrupt_Entry : constant := -2;
228
229   Cancelled_Entry : constant := -1;
230
231   type Entry_Index is range Interrupt_Entry .. Max_Entry;
232
233   Null_Task_Entry : constant := Null_Entry;
234
235   Max_Task_Entry : constant := Max_Entry;
236
237   type Task_Entry_Index is new Entry_Index
238     range Null_Task_Entry .. Max_Task_Entry;
239
240   type Entry_Call_Record;
241
242   type Entry_Call_Link is access all Entry_Call_Record;
243
244   type Entry_Queue is record
245      Head : Entry_Call_Link;
246      Tail : Entry_Call_Link;
247   end record;
248
249   type Task_Entry_Queue_Array is
250     array (Task_Entry_Index range <>) of Entry_Queue;
251
252   --  A data structure which contains the string names of entries and entry
253   --  family members.
254
255   type String_Access is access all String;
256
257   type Task_Entry_Names_Array is
258     array (Entry_Index range <>) of String_Access;
259
260   type Task_Entry_Names_Access is access all Task_Entry_Names_Array;
261
262   ----------------------------------
263   -- Entry_Call_Record definition --
264   ----------------------------------
265
266   type Entry_Call_State is
267     (Never_Abortable,
268      --  the call is not abortable, and never can be
269
270      Not_Yet_Abortable,
271      --  the call is not abortable, but may become so
272
273      Was_Abortable,
274      --  the call is not abortable, but once was
275
276      Now_Abortable,
277      --  the call is abortable
278
279      Done,
280      --  the call has been completed
281
282      Cancelled
283      --  the call was asynchronous, and was cancelled
284     );
285   pragma Ordered (Entry_Call_State);
286
287   --  Never_Abortable is used for calls that are made in a abort deferred
288   --  region (see ARM 9.8(5-11), 9.8 (20)). Such a call is never abortable.
289
290   --  The Was_ vs. Not_Yet_ distinction is needed to decide whether it is OK
291   --  to advance into the abortable part of an async. select stmt. That is
292   --  allowed iff the mode is Now_ or Was_.
293
294   --  Done indicates the call has been completed, without cancellation, or no
295   --  call has been made yet at this ATC nesting level, and so aborting the
296   --  call is no longer an issue. Completion of the call does not necessarily
297   --  indicate "success"; the call may be returning an exception if
298   --  Exception_To_Raise is non-null.
299
300   --  Cancelled indicates the call was cancelled, and so aborting the call is
301   --  no longer an issue.
302
303   --  The call is on an entry queue unless State >= Done, in which case it may
304   --  or may not be still Onqueue.
305
306   --  Please do not modify the order of the values, without checking all uses
307   --  of this type. We rely on partial "monotonicity" of
308   --  Entry_Call_Record.State to avoid locking when we access this value for
309   --  certain tests. In particular:
310
311   --  1)  Once State >= Done, we can rely that the call has been
312   --      completed. If State >= Done, it will not
313   --      change until the task does another entry call at this level.
314
315   --  2)  Once State >= Was_Abortable, we can rely that the call has
316   --      been queued abortably at least once, and so the check for
317   --      whether it is OK to advance to the abortable part of an
318   --      async. select statement does not need to lock anything.
319
320   type Restricted_Entry_Call_Record is record
321      Self : Task_Id;
322      --  ID of the caller
323
324      Mode : Call_Modes;
325
326      State : Entry_Call_State;
327      pragma Atomic (State);
328      --  Indicates part of the state of the call.
329      --
330      --  Protection: If the call is not on a queue, it should only be
331      --  accessed by Self, and Self does not need any lock to modify this
332      --  field.
333      --
334      --  Once the call is on a queue, the value should be something other
335      --  than Done unless it is cancelled, and access is controller by the
336      --  "server" of the queue -- i.e., the lock of Checked_To_Protection
337      --  (Call_Target) if the call record is on the queue of a PO, or the
338      --  lock of Called_Target if the call is on the queue of a task. See
339      --  comments on type declaration for more details.
340
341      Uninterpreted_Data : System.Address;
342      --  Data passed by the compiler
343
344      Exception_To_Raise : Ada.Exceptions.Exception_Id;
345      --  The exception to raise once this call has been completed without
346      --  being aborted.
347   end record;
348   pragma Suppress_Initialization (Restricted_Entry_Call_Record);
349
350   -------------------------------------------
351   -- Task termination procedure definition --
352   -------------------------------------------
353
354   --  We need to redefine here these types (already defined in
355   --  Ada.Task_Termination) for avoiding circular dependencies.
356
357   type Cause_Of_Termination is (Normal, Abnormal, Unhandled_Exception);
358   --  Possible causes for task termination:
359   --
360   --    Normal means that the task terminates due to completing the
361   --    last sentence of its body, or as a result of waiting on a
362   --    terminate alternative.
363
364   --    Abnormal means that the task terminates because it is being aborted
365
366   --    handled_Exception means that the task terminates because of exception
367   --    raised by the execution of its task_body.
368
369   type Termination_Handler is access protected procedure
370     (Cause : Cause_Of_Termination;
371      T     : Task_Id;
372      X     : Ada.Exceptions.Exception_Occurrence);
373   --  Used to represent protected procedures to be executed when task
374   --  terminates.
375
376   ------------------------------------
377   -- Dispatching domain definitions --
378   ------------------------------------
379
380   --  We need to redefine here these types (already defined in
381   --  System.Multiprocessor.Dispatching_Domains) for avoiding circular
382   --  dependencies.
383
384   type Dispatching_Domain is
385     array (System.Multiprocessors.CPU range <>) of Boolean;
386   --  A dispatching domain needs to contain the set of processors belonging
387   --  to it. This is a processor mask where a True indicates that the
388   --  processor belongs to the dispatching domain.
389   --  Do not use the full range of CPU_Range because it would create a very
390   --  long array. This way we can use the exact range of processors available
391   --  in the system.
392
393   type Dispatching_Domain_Access is access Dispatching_Domain;
394
395   System_Domain : Dispatching_Domain_Access;
396   --  All processors belong to default system dispatching domain at start up.
397   --  We use a pointer which creates the actual variable for the reasons
398   --  explained bellow in Dispatching_Domain_Tasks.
399
400   Dispatching_Domains_Frozen : Boolean := False;
401   --  True when the main procedure has been called. Hence, no new dispatching
402   --  domains can be created when this flag is True.
403
404   type Array_Allocated_Tasks is
405     array (System.Multiprocessors.CPU range <>) of Natural;
406   --  At start-up time, we need to store the number of tasks attached to
407   --  concrete processors within the system domain (we can only create
408   --  dispatching domains with processors belonging to the system domain and
409   --  without tasks allocated).
410
411   type Array_Allocated_Tasks_Access is access Array_Allocated_Tasks;
412
413   Dispatching_Domain_Tasks : Array_Allocated_Tasks_Access;
414   --  We need to store whether there are tasks allocated to concrete
415   --  processors in the default system dispatching domain because we need to
416   --  check it before creating a new dispatching domain. Two comments about
417   --  why we use a pointer here and not in package Dispatching_Domains:
418   --
419   --    1) We use an array created dynamically in procedure Initialize which
420   --    is called at the beginning of the initialization of the run-time
421   --    library. Declaring a static array here in the spec would not work
422   --    across different installations because it would get the value of
423   --    Number_Of_CPUs from the machine where the run-time library is built,
424   --    and not from the machine where the application is executed. That is
425   --    the reason why we create the array (CPU'First .. Number_Of_CPUs) at
426   --    execution time in the procedure body, ensuring that the function
427   --    Number_Of_CPUs is executed at execution time (the same trick as we
428   --    use for System_Domain).
429   --
430   --    2) We have moved this declaration from package Dispatching_Domains
431   --    because when we use a pragma CPU, the affinity is passed through the
432   --    call to Create_Task. Hence, at this point, we may need to update the
433   --    number of tasks associated to the processor, but we do not want to
434   --    force a dependency from this package on Dispatching_Domains.
435
436   ------------------------------------
437   -- Task related other definitions --
438   ------------------------------------
439
440   type Activation_Chain is limited private;
441   --  Linked list of to-be-activated tasks, linked through
442   --  Activation_Link. The order of tasks on the list is irrelevant, because
443   --  the priority rules will ensure that they actually start activating in
444   --  priority order.
445
446   type Activation_Chain_Access is access all Activation_Chain;
447
448   type Task_Procedure_Access is access procedure (Arg : System.Address);
449
450   type Access_Boolean is access all Boolean;
451
452   function Detect_Blocking return Boolean;
453   pragma Inline (Detect_Blocking);
454   --  Return whether the Detect_Blocking pragma is enabled
455
456   function Storage_Size (T : Task_Id) return System.Parameters.Size_Type;
457   --  Retrieve from the TCB of the task the allocated size of its stack,
458   --  either the system default or the size specified by a pragma. This is in
459   --  general a non-static value that can depend on discriminants of the task.
460
461   type Bit_Array is array (Integer range <>) of Boolean;
462   pragma Pack (Bit_Array);
463
464   subtype Debug_Event_Array is Bit_Array (1 .. 16);
465
466   Global_Task_Debug_Event_Set : Boolean := False;
467   --  Set True when running under debugger control and a task debug event
468   --  signal has been requested.
469
470   ----------------------------------------------
471   -- Ada_Task_Control_Block (ATCB) definition --
472   ----------------------------------------------
473
474   --  Notes on protection (synchronization) of TRTS data structures
475
476   --  Any field of the TCB can be written by the activator of a task when the
477   --  task is created, since no other task can access the new task's
478   --  state until creation is complete.
479
480   --  The protection for each field is described in a comment starting with
481   --  "Protection:".
482
483   --  When a lock is used to protect an ATCB field, this lock is simply named
484
485   --  Some protection is described in terms of tasks related to the
486   --  ATCB being protected. These are:
487
488   --    Self:      The task which is controlled by this ATCB
489   --    Acceptor:  A task accepting a call from Self
490   --    Caller:    A task calling an entry of Self
491   --    Parent:    The task executing the master on which Self depends
492   --    Dependent: A task dependent on Self
493   --    Activator: The task that created Self and initiated its activation
494   --    Created:   A task created and activated by Self
495
496   --  Note: The order of the fields is important to implement efficiently
497   --  tasking support under gdb.
498   --  Currently gdb relies on the order of the State, Parent, Base_Priority,
499   --  Task_Image, Task_Image_Len, Call and LL fields.
500
501   -------------------------
502   -- Common ATCB section --
503   -------------------------
504
505   --  Section used by all GNARL implementations (regular and restricted)
506
507   type Common_ATCB is limited record
508      State : Task_States;
509      pragma Atomic (State);
510      --  Encodes some basic information about the state of a task,
511      --  including whether it has been activated, whether it is sleeping,
512      --  and whether it is terminated.
513      --
514      --  Protection: Self.L
515
516      Parent : Task_Id;
517      --  The task on which this task depends.
518      --  See also Master_Level and Master_Within.
519
520      Base_Priority : System.Any_Priority;
521      --  Base priority, not changed during entry calls, only changed
522      --  via dynamic priorities package.
523      --
524      --  Protection: Only written by Self, accessed by anyone
525
526      Base_CPU : System.Multiprocessors.CPU_Range;
527      --  Base CPU, only changed via dispatching domains package.
528      --
529      --  Protection: Self.L
530
531      Current_Priority : System.Any_Priority;
532      --  Active priority, except that the effects of protected object
533      --  priority ceilings are not reflected. This only reflects explicit
534      --  priority changes and priority inherited through task activation
535      --  and rendezvous.
536      --
537      --  Ada 95 notes: In Ada 95, this field will be transferred to the
538      --  Priority field of an Entry_Calls component when an entry call is
539      --  initiated. The Priority of the Entry_Calls component will not change
540      --  for the duration of the call. The accepting task can use it to boost
541      --  its own priority without fear of its changing in the meantime.
542      --
543      --  This can safely be used in the priority ordering of entry queues.
544      --  Once a call is queued, its priority does not change.
545      --
546      --  Since an entry call cannot be made while executing a protected
547      --  action, the priority of a task will never reflect a priority ceiling
548      --  change at the point of an entry call.
549      --
550      --  Protection: Only written by Self, and only accessed when Acceptor
551      --  accepts an entry or when Created activates, at which points Self is
552      --  suspended.
553
554      Protected_Action_Nesting : Natural;
555      pragma Atomic (Protected_Action_Nesting);
556      --  The dynamic level of protected action nesting for this task. This
557      --  field is needed for checking whether potentially blocking operations
558      --  are invoked from protected actions. pragma Atomic is used because it
559      --  can be read/written from protected interrupt handlers.
560
561      Task_Image : String (1 .. System.Parameters.Max_Task_Image_Length);
562      --  Hold a string that provides a readable id for task, built from the
563      --  variable of which it is a value or component.
564
565      Task_Image_Len : Natural;
566      --  Actual length of Task_Image
567
568      Call : Entry_Call_Link;
569      --  The entry call that has been accepted by this task.
570      --
571      --  Protection: Self.L. Self will modify this field when Self.Accepting
572      --  is False, and will not need the mutex to do so. Once a task sets
573      --  Pending_ATC_Level = 0, no other task can access this field.
574
575      LL : aliased Task_Primitives.Private_Data;
576      --  Control block used by the underlying low-level tasking service
577      --  (GNULLI).
578      --
579      --  Protection: This is used only by the GNULLI implementation, which
580      --  takes care of all of its synchronization.
581
582      Task_Arg : System.Address;
583      --  The argument to task procedure. Provide a handle for discriminant
584      --  information.
585      --
586      --  Protection: Part of the synchronization between Self and Activator.
587      --  Activator writes it, once, before Self starts executing. Thereafter,
588      --  Self only reads it.
589
590      Task_Alternate_Stack : System.Address;
591      --  The address of the alternate signal stack for this task, if any
592      --
593      --  Protection: Only accessed by Self
594
595      Task_Entry_Point : Task_Procedure_Access;
596      --  Information needed to call the procedure containing the code for
597      --  the body of this task.
598      --
599      --  Protection: Part of the synchronization between Self and Activator.
600      --  Activator writes it, once, before Self starts executing. Self reads
601      --  it, once, as part of its execution.
602
603      Compiler_Data : System.Soft_Links.TSD;
604      --  Task-specific data needed by the compiler to store per-task
605      --  structures.
606      --
607      --  Protection: Only accessed by Self
608
609      All_Tasks_Link : Task_Id;
610      --  Used to link this task to the list of all tasks in the system
611      --
612      --  Protection: RTS_Lock
613
614      Activation_Link : Task_Id;
615      --  Used to link this task to a list of tasks to be activated
616      --
617      --  Protection: Only used by Activator
618
619      Activator : Task_Id;
620      pragma Atomic (Activator);
621      --  The task that created this task, either by declaring it as a task
622      --  object or by executing a task allocator. The value is null iff Self
623      --  has completed activation.
624      --
625      --  Protection: Set by Activator before Self is activated, and
626      --  only modified by Self after that. Can be read by any task via
627      --  Ada.Task_Identification.Activation_Is_Complete; hence Atomic.
628
629      Wait_Count : Natural;
630      --  This count is used by a task that is waiting for other tasks. At all
631      --  other times, the value should be zero. It is used differently in
632      --  several different states. Since a task cannot be in more than one of
633      --  these states at the same time, a single counter suffices.
634      --
635      --  Protection: Self.L
636
637      --  Activator_Sleep
638
639      --  This is the number of tasks that this task is activating, i.e. the
640      --  children that have started activation but have not completed it.
641      --
642      --  Protection: Self.L and Created.L. Both mutexes must be locked, since
643      --  Self.Activation_Count and Created.State must be synchronized.
644
645      --  Master_Completion_Sleep (phase 1)
646
647      --  This is the number dependent tasks of a master being completed by
648      --  Self that are activated, but have not yet terminated, and are not
649      --  waiting on a terminate alternative.
650
651      --  Master_Completion_2_Sleep (phase 2)
652
653      --  This is the count of tasks dependent on a master being completed by
654      --  Self which are waiting on a terminate alternative.
655
656      Elaborated : Access_Boolean;
657      --  Pointer to a flag indicating that this task's body has been
658      --  elaborated. The flag is created and managed by the
659      --  compiler-generated code.
660      --
661      --  Protection: The field itself is only accessed by Activator. The flag
662      --  that it points to is updated by Master and read by Activator; access
663      --  is assumed to be atomic.
664
665      Activation_Failed : Boolean;
666      --  Set to True if activation of a chain of tasks fails,
667      --  so that the activator should raise Tasking_Error.
668
669      Task_Info : System.Task_Info.Task_Info_Type;
670      --  System-specific attributes of the task as specified by the
671      --  Task_Info pragma.
672
673      Analyzer : System.Stack_Usage.Stack_Analyzer;
674      --  For storing information used to measure the stack usage
675
676      Global_Task_Lock_Nesting : Natural;
677      --  This is the current nesting level of calls to
678      --  System.Tasking.Initialization.Lock_Task. This allows a task to call
679      --  Lock_Task multiple times without deadlocking. A task only locks
680      --  Global_Task_Lock when its Global_Task_Lock_Nesting goes from 0 to 1,
681      --  and only unlocked when it goes from 1 to 0.
682      --
683      --  Protection: Only accessed by Self
684
685      Fall_Back_Handler : Termination_Handler;
686      --  This is the fall-back handler that applies to the dependent tasks of
687      --  the task.
688      --
689      --  Protection: Self.L
690
691      Specific_Handler : Termination_Handler;
692      --  This is the specific handler that applies only to this task, and not
693      --  any of its dependent tasks.
694      --
695      --  Protection: Self.L
696
697      Debug_Events : Debug_Event_Array;
698      --  Word length array of per task debug events, of which 11 kinds are
699      --  currently defined in System.Tasking.Debugging package.
700
701      Domain : Dispatching_Domain_Access;
702      --  Domain is the dispatching domain to which the task belongs. It is
703      --  only changed via dispatching domains package. This field is made
704      --  part of the Common_ATCB, even when restricted run-times (namely
705      --  Ravenscar) do not use it, because this way the field is always
706      --  available to the underlying layers to set the affinity and we do not
707      --  need to do different things depending on the situation.
708      --
709      --  Protection: Self.L
710   end record;
711
712   ---------------------------------------
713   -- Restricted_Ada_Task_Control_Block --
714   ---------------------------------------
715
716   --  This type should only be used by the restricted GNARLI and by restricted
717   --  GNULL implementations to allocate an ATCB (see System.Task_Primitives.
718   --  Operations.New_ATCB) that will take significantly less memory.
719
720   --  Note that the restricted GNARLI should only access fields that are
721   --  present in the Restricted_Ada_Task_Control_Block structure.
722
723   type Restricted_Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is
724   limited record
725      Common : Common_ATCB;
726      --  The common part between various tasking implementations
727
728      Entry_Call : aliased Restricted_Entry_Call_Record;
729      --  Protection: This field is used on entry call "queues" associated
730      --  with protected objects, and is protected by the protected object
731      --  lock.
732   end record;
733   pragma Suppress_Initialization (Restricted_Ada_Task_Control_Block);
734
735   Interrupt_Manager_ID : Task_Id;
736   --  This task ID is declared here to break circular dependencies.
737   --  Also declare Interrupt_Manager_ID after Task_Id is known, to avoid
738   --  generating unneeded finalization code.
739
740   -----------------------
741   -- List of all Tasks --
742   -----------------------
743
744   All_Tasks_List : Task_Id;
745   --  Global linked list of all tasks
746
747   ------------------------------------------
748   -- Regular (non restricted) definitions --
749   ------------------------------------------
750
751   --------------------------------
752   -- Master Related Definitions --
753   --------------------------------
754
755   subtype Master_Level is Integer;
756   subtype Master_ID is Master_Level;
757
758   --  Normally, a task starts out with internal master nesting level one
759   --  larger than external master nesting level. It is incremented by one by
760   --  Enter_Master, which is called in the task body only if the compiler
761   --  thinks the task may have dependent tasks. It is set to 1 for the
762   --  environment task, the level 2 is reserved for server tasks of the
763   --  run-time system (the so called "independent tasks"), and the level 3 is
764   --  for the library level tasks. Foreign threads which are detected by
765   --  the run-time have a level of 0, allowing these tasks to be easily
766   --  distinguished if needed.
767
768   Foreign_Task_Level     : constant Master_Level := 0;
769   Environment_Task_Level : constant Master_Level := 1;
770   Independent_Task_Level : constant Master_Level := 2;
771   Library_Task_Level     : constant Master_Level := 3;
772
773   -------------------
774   -- Priority info --
775   -------------------
776
777   Unspecified_Priority : constant Integer := System.Priority'First - 1;
778
779   Priority_Not_Boosted : constant Integer := System.Priority'First - 1;
780   --  Definition of Priority actually has to come from the RTS configuration
781
782   subtype Rendezvous_Priority is Integer
783     range Priority_Not_Boosted .. System.Any_Priority'Last;
784
785   -------------------
786   -- Affinity info --
787   -------------------
788
789   Unspecified_CPU : constant := -1;
790   --  No affinity specified
791
792   ------------------------------------
793   -- Rendezvous related definitions --
794   ------------------------------------
795
796   No_Rendezvous : constant := 0;
797
798   Max_Select : constant Integer := Integer'Last;
799   --  RTS-defined
800
801   subtype Select_Index is Integer range No_Rendezvous .. Max_Select;
802   --   type Select_Index is range No_Rendezvous .. Max_Select;
803
804   subtype Positive_Select_Index is
805     Select_Index range 1 .. Select_Index'Last;
806
807   type Accept_Alternative is record
808      Null_Body : Boolean;
809      S         : Task_Entry_Index;
810   end record;
811
812   type Accept_List is
813     array (Positive_Select_Index range <>) of Accept_Alternative;
814
815   type Accept_List_Access is access constant Accept_List;
816
817   -----------------------------------
818   -- ATC_Level related definitions --
819   -----------------------------------
820
821   Max_ATC_Nesting : constant Natural := 20;
822
823   subtype ATC_Level_Base is Integer range 0 .. Max_ATC_Nesting;
824
825   ATC_Level_Infinity : constant ATC_Level_Base := ATC_Level_Base'Last;
826
827   subtype ATC_Level is ATC_Level_Base range 0 .. ATC_Level_Base'Last - 1;
828
829   subtype ATC_Level_Index is ATC_Level range 1 .. ATC_Level'Last;
830
831   ----------------------------------
832   -- Entry_Call_Record definition --
833   ----------------------------------
834
835   type Entry_Call_Record is record
836      Self  : Task_Id;
837      --  ID of the caller
838
839      Mode : Call_Modes;
840
841      State : Entry_Call_State;
842      pragma Atomic (State);
843      --  Indicates part of the state of the call
844      --
845      --  Protection: If the call is not on a queue, it should only be
846      --  accessed by Self, and Self does not need any lock to modify this
847      --  field. Once the call is on a queue, the value should be something
848      --  other than Done unless it is cancelled, and access is controller by
849      --  the "server" of the queue -- i.e., the lock of Checked_To_Protection
850      --  (Call_Target) if the call record is on the queue of a PO, or the
851      --  lock of Called_Target if the call is on the queue of a task. See
852      --  comments on type declaration for more details.
853
854      Uninterpreted_Data : System.Address;
855      --  Data passed by the compiler
856
857      Exception_To_Raise : Ada.Exceptions.Exception_Id;
858      --  The exception to raise once this call has been completed without
859      --  being aborted.
860
861      Prev : Entry_Call_Link;
862
863      Next : Entry_Call_Link;
864
865      Level : ATC_Level;
866      --  One of Self and Level are redundant in this implementation, since
867      --  each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must
868      --  have access to the entry call record to be reading this, we could
869      --  get Self from Level, or Level from Self. However, this requires
870      --  non-portable address arithmetic.
871
872      E : Entry_Index;
873
874      Prio : System.Any_Priority;
875
876      --  The above fields are those that there may be some hope of packing.
877      --  They are gathered together to allow for compilers that lay records
878      --  out contiguously, to allow for such packing.
879
880      Called_Task : Task_Id;
881      pragma Atomic (Called_Task);
882      --  Use for task entry calls. The value is null if the call record is
883      --  not in use. Conversely, unless State is Done and Onqueue is false,
884      --  Called_Task points to an ATCB.
885      --
886      --  Protection:  Called_Task.L
887
888      Called_PO : System.Address;
889      pragma Atomic (Called_PO);
890      --  Similar to Called_Task but for protected objects
891      --
892      --  Note that the previous implementation tried to merge both
893      --  Called_Task and Called_PO but this ended up in many unexpected
894      --  complications (e.g having to add a magic number in the ATCB, which
895      --  caused gdb lots of confusion) with no real gain since the
896      --  Lock_Server implementation still need to loop around chasing for
897      --  pointer changes even with a single pointer.
898
899      Acceptor_Prev_Call : Entry_Call_Link;
900      --  For task entry calls only
901
902      Acceptor_Prev_Priority : Rendezvous_Priority := Priority_Not_Boosted;
903      --  For task entry calls only. The priority of the most recent prior
904      --  call being serviced. For protected entry calls, this function should
905      --  be performed by GNULLI ceiling locking.
906
907      Cancellation_Attempted : Boolean := False;
908      pragma Atomic (Cancellation_Attempted);
909      --  Cancellation of the call has been attempted.
910      --  Consider merging this into State???
911
912      With_Abort : Boolean := False;
913      --  Tell caller whether the call may be aborted
914      --  ??? consider merging this with Was_Abortable state
915
916      Needs_Requeue : Boolean := False;
917      --  Temporary to tell acceptor of task entry call that
918      --  Exceptional_Complete_Rendezvous needs to do requeue.
919   end record;
920
921   ------------------------------------
922   -- Task related other definitions --
923   ------------------------------------
924
925   type Access_Address is access all System.Address;
926   --  Anonymous pointer used to implement task attributes (see s-tataat.adb
927   --  and a-tasatt.adb)
928
929   pragma No_Strict_Aliasing (Access_Address);
930   --  This type is used in contexts where aliasing may be an issue (see
931   --  for example s-tataat.adb), so we avoid any incorrect aliasing
932   --  assumptions.
933
934   ----------------------------------------------
935   -- Ada_Task_Control_Block (ATCB) definition --
936   ----------------------------------------------
937
938   type Entry_Call_Array is array (ATC_Level_Index) of
939     aliased Entry_Call_Record;
940
941   type Atomic_Address is mod Memory_Size;
942   pragma Atomic (Atomic_Address);
943   type Attribute_Array is
944     array (1 .. Parameters.Max_Attribute_Count) of Atomic_Address;
945   --  Array of task attributes. The value (Atomic_Address) will either be
946   --  converted to a task attribute if it fits, or to a pointer to a record
947   --  by Ada.Task_Attributes.
948
949   type Task_Serial_Number is mod 2 ** Long_Long_Integer'Size;
950   --  Used to give each task a unique serial number. We want 64-bits for this
951   --  type to get as much uniqueness as possible (2**64 is operationally
952   --  infinite in this context, but 2**32 perhaps could recycle). We use
953   --  Long_Long_Integer (which in the normal case is always 64-bits) rather
954   --  than 64-bits explicitly to allow codepeer to analyze this unit when
955   --  a target configuration file forces the maximum integer size to 32.
956
957   type Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is limited record
958      Common : Common_ATCB;
959      --  The common part between various tasking implementations
960
961      Entry_Calls : Entry_Call_Array;
962      --  An array of entry calls
963      --
964      --  Protection: The elements of this array are on entry call queues
965      --  associated with protected objects or task entries, and are protected
966      --  by the protected object lock or Acceptor.L, respectively.
967
968      Entry_Names : Task_Entry_Names_Access := null;
969      --  An array of string names which denotes entry [family member] names.
970      --  The structure is indexed by task entry index and contains Entry_Num
971      --  components.
972      --
973      --  Protection: The array is populated during task initialization, before
974      --  the task has been activated. No protection is required in this case.
975
976      New_Base_Priority : System.Any_Priority;
977      --  New value for Base_Priority (for dynamic priorities package)
978      --
979      --  Protection: Self.L
980
981      Open_Accepts : Accept_List_Access;
982      --  This points to the Open_Accepts array of accept alternatives passed
983      --  to the RTS by the compiler-generated code to Selective_Wait. It is
984      --  non-null iff this task is ready to accept an entry call.
985      --
986      --  Protection: Self.L
987
988      Chosen_Index : Select_Index;
989      --  The index in Open_Accepts of the entry call accepted by a selective
990      --  wait executed by this task.
991      --
992      --  Protection: Written by both Self and Caller. Usually protected by
993      --  Self.L. However, once the selection is known to have been written it
994      --  can be accessed without protection. This happens after Self has
995      --  updated it itself using information from a suspended Caller, or
996      --  after Caller has updated it and awakened Self.
997
998      Master_of_Task : Master_Level;
999      --  The task executing the master of this task, and the ID of this task's
1000      --  master (unique only among masters currently active within Parent).
1001      --
1002      --  Protection: Set by Activator before Self is activated, and read
1003      --  after Self is activated.
1004
1005      Master_Within : Master_Level;
1006      --  The ID of the master currently executing within this task; that is,
1007      --  the most deeply nested currently active master.
1008      --
1009      --  Protection: Only written by Self, and only read by Self or by
1010      --  dependents when Self is attempting to exit a master. Since Self will
1011      --  not write this field until the master is complete, the
1012      --  synchronization should be adequate to prevent races.
1013
1014      Alive_Count : Natural := 0;
1015      --  Number of tasks directly dependent on this task (including itself)
1016      --  that are still "alive", i.e. not terminated.
1017      --
1018      --  Protection: Self.L
1019
1020      Awake_Count : Natural := 0;
1021      --  Number of tasks directly dependent on this task (including itself)
1022      --  still "awake", i.e., are not terminated and not waiting on a
1023      --  terminate alternative.
1024      --
1025      --  Invariant: Awake_Count <= Alive_Count
1026
1027      --  Protection: Self.L
1028
1029      --  Beginning of flags
1030
1031      Aborting : Boolean := False;
1032      pragma Atomic (Aborting);
1033      --  Self is in the process of aborting. While set, prevents multiple
1034      --  abort signals from being sent by different aborter while abort
1035      --  is acted upon. This is essential since an aborter which calls
1036      --  Abort_To_Level could set the Pending_ATC_Level to yet a lower level
1037      --  (than the current level), may be preempted and would send the
1038      --  abort signal when resuming execution. At this point, the abortee
1039      --  may have completed abort to the proper level such that the
1040      --  signal (and resulting abort exception) are not handled any more.
1041      --  In other words, the flag prevents a race between multiple aborters
1042      --
1043      --  Protection: protected by atomic access.
1044
1045      ATC_Hack : Boolean := False;
1046      pragma Atomic (ATC_Hack);
1047      --  ?????
1048      --  Temporary fix, to allow Undefer_Abort to reset Aborting in the
1049      --  handler for Abort_Signal that encloses an async. entry call.
1050      --  For the longer term, this should be done via code in the
1051      --  handler itself.
1052
1053      Callable : Boolean := True;
1054      --  It is OK to call entries of this task
1055
1056      Dependents_Aborted : Boolean := False;
1057      --  This is set to True by whichever task takes responsibility for
1058      --  aborting the dependents of this task.
1059      --
1060      --  Protection: Self.L
1061
1062      Interrupt_Entry : Boolean := False;
1063      --  Indicates if one or more Interrupt Entries are attached to the task.
1064      --  This flag is needed for cleaning up the Interrupt Entry bindings.
1065
1066      Pending_Action : Boolean := False;
1067      --  Unified flag indicating some action needs to be take when abort
1068      --  next becomes undeferred. Currently set if:
1069      --  . Pending_Priority_Change is set
1070      --  . Pending_ATC_Level is changed
1071      --  . Requeue involving POs
1072      --    (Abortable field may have changed and the Wait_Until_Abortable
1073      --     has to recheck the abortable status of the call.)
1074      --  . Exception_To_Raise is non-null
1075      --
1076      --  Protection: Self.L
1077      --
1078      --  This should never be reset back to False outside of the procedure
1079      --  Do_Pending_Action, which is called by Undefer_Abort. It should only
1080      --  be set to True by Set_Priority and Abort_To_Level.
1081
1082      Pending_Priority_Change : Boolean := False;
1083      --  Flag to indicate pending priority change (for dynamic priorities
1084      --  package). The base priority is updated on the next abort
1085      --  completion point (aka. synchronization point).
1086      --
1087      --  Protection: Self.L
1088
1089      Terminate_Alternative : Boolean := False;
1090      --  Task is accepting Select with Terminate Alternative
1091      --
1092      --  Protection: Self.L
1093
1094      --  End of flags
1095
1096      --  Beginning of counts
1097
1098      ATC_Nesting_Level : ATC_Level := 1;
1099      --  The dynamic level of ATC nesting (currently executing nested
1100      --  asynchronous select statements) in this task.
1101
1102      --  Protection: Self_ID.L. Only Self reads or updates this field.
1103      --  Decrementing it deallocates an Entry_Calls component, and care must
1104      --  be taken that all references to that component are eliminated before
1105      --  doing the decrement. This in turn will require locking a protected
1106      --  object (for a protected entry call) or the Acceptor's lock (for a
1107      --  task entry call). No other task should attempt to read or modify
1108      --  this value.
1109
1110      Deferral_Level : Natural := 1;
1111      --  This is the number of times that Defer_Abort has been called by
1112      --  this task without a matching Undefer_Abort call. Abortion is only
1113      --  allowed when this zero. It is initially 1, to protect the task at
1114      --  startup.
1115
1116      --  Protection: Only updated by Self; access assumed to be atomic
1117
1118      Pending_ATC_Level : ATC_Level_Base := ATC_Level_Infinity;
1119      --  The ATC level to which this task is currently being aborted. If the
1120      --  value is zero, the entire task has "completed". That may be via
1121      --  abort, exception propagation, or normal exit. If the value is
1122      --  ATC_Level_Infinity, the task is not being aborted to any level. If
1123      --  the value is positive, the task has not completed. This should ONLY
1124      --  be modified by Abort_To_Level and Exit_One_ATC_Level.
1125      --
1126      --  Protection: Self.L
1127
1128      Serial_Number : Task_Serial_Number;
1129      --  Monotonic counter to provide some way to check locking rules/ordering
1130
1131      Known_Tasks_Index : Integer := -1;
1132      --  Index in the System.Tasking.Debug.Known_Tasks array
1133
1134      User_State : Long_Integer := 0;
1135      --  User-writeable location, for use in debugging tasks; also provides a
1136      --  simple task specific data.
1137
1138      Attributes : Attribute_Array := (others => 0);
1139      --  Task attributes
1140
1141      Entry_Queues : Task_Entry_Queue_Array (1 .. Entry_Num);
1142      --  An array of task entry queues
1143      --
1144      --  Protection: Self.L. Once a task has set Self.Stage to Completing, it
1145      --  has exclusive access to this field.
1146
1147      Free_On_Termination : Boolean := False;
1148      --  Deallocate the ATCB when the task terminates. This flag is normally
1149      --  False, and is set True when Unchecked_Deallocation is called on a
1150      --  non-terminated task so that the associated storage is automatically
1151      --  reclaimed when the task terminates.
1152   end record;
1153
1154   --------------------
1155   -- Initialization --
1156   --------------------
1157
1158   procedure Initialize;
1159   --  This procedure constitutes the first part of the initialization of the
1160   --  GNARL. This includes creating data structures to make the initial thread
1161   --  into the environment task. The last part of the initialization is done
1162   --  in System.Tasking.Initialization or System.Tasking.Restricted.Stages.
1163   --  All the initializations used to be in Tasking.Initialization, but this
1164   --  is no longer possible with the run time simplification (including
1165   --  optimized PO and the restricted run time) since one cannot rely on
1166   --  System.Tasking.Initialization being present, as was done before.
1167
1168   procedure Initialize_ATCB
1169     (Self_ID          : Task_Id;
1170      Task_Entry_Point : Task_Procedure_Access;
1171      Task_Arg         : System.Address;
1172      Parent           : Task_Id;
1173      Elaborated       : Access_Boolean;
1174      Base_Priority    : System.Any_Priority;
1175      Base_CPU         : System.Multiprocessors.CPU_Range;
1176      Domain           : Dispatching_Domain_Access;
1177      Task_Info        : System.Task_Info.Task_Info_Type;
1178      Stack_Size       : System.Parameters.Size_Type;
1179      T                : Task_Id;
1180      Success          : out Boolean);
1181   --  Initialize fields of the TCB for task T, and link into global TCB
1182   --  structures. Call this only with abort deferred and holding RTS_Lock.
1183   --  Self_ID is the calling task (normally the activator of T). Success is
1184   --  set to indicate whether the TCB was successfully initialized.
1185
1186private
1187
1188   Null_Task : constant Task_Id := null;
1189
1190   type Activation_Chain is limited record
1191      T_ID : Task_Id;
1192   end record;
1193
1194   --  Activation_Chain is an in-out parameter of initialization procedures and
1195   --  it must be passed by reference because the init proc may terminate
1196   --  abnormally after creating task components, and these must be properly
1197   --  registered for removal (Expunge_Unactivated_Tasks). The "limited" forces
1198   --  Activation_Chain to be a by-reference type; see RM-6.2(4).
1199
1200   function Number_Of_Entries (Self_Id : Task_Id) return Entry_Index;
1201   --  Given a task, return the number of entries it contains
1202
1203   procedure Set_Entry_Names
1204     (Self_Id : Task_Id;
1205      Names   : Task_Entry_Names_Access);
1206   --  Associate an array of strings denotinge entry [family] names with a task
1207
1208end System.Tasking;
1209