File : s-taskin.ads
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-2015, 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 -- --
19 -- --
20 -- --
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
37 with Ada.Exceptions;
38 with Ada.Unchecked_Conversion;
39
40 with System.Parameters;
41 with System.Task_Info;
42 with System.Soft_Links;
43 with System.Task_Primitives;
44 with System.Stack_Usage;
45 with System.Multiprocessors;
46
47 package 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 Free_On_Termination : Boolean := False;
1139 -- Deallocate the ATCB when the task terminates. This flag is normally
1140 -- False, and is set True when Unchecked_Deallocation is called on a
1141 -- non-terminated task so that the associated storage is automatically
1142 -- reclaimed when the task terminates.
1143
1144 Attributes : Attribute_Array := (others => 0);
1145 -- Task attributes
1146
1147 -- IMPORTANT Note: the Entry_Queues field is last for efficiency of
1148 -- access to other fields, do not put new fields after this one.
1149
1150 Entry_Queues : Task_Entry_Queue_Array (1 .. Entry_Num);
1151 -- An array of task entry queues
1152 --
1153 -- Protection: Self.L. Once a task has set Self.Stage to Completing, it
1154 -- has exclusive access to this field.
1155 end record;
1156
1157 --------------------
1158 -- Initialization --
1159 --------------------
1160
1161 procedure Initialize;
1162 -- This procedure constitutes the first part of the initialization of the
1163 -- GNARL. This includes creating data structures to make the initial thread
1164 -- into the environment task. The last part of the initialization is done
1165 -- in System.Tasking.Initialization or System.Tasking.Restricted.Stages.
1166 -- All the initializations used to be in Tasking.Initialization, but this
1167 -- is no longer possible with the run time simplification (including
1168 -- optimized PO and the restricted run time) since one cannot rely on
1169 -- System.Tasking.Initialization being present, as was done before.
1170
1171 procedure Initialize_ATCB
1172 (Self_ID : Task_Id;
1173 Task_Entry_Point : Task_Procedure_Access;
1174 Task_Arg : System.Address;
1175 Parent : Task_Id;
1176 Elaborated : Access_Boolean;
1177 Base_Priority : System.Any_Priority;
1178 Base_CPU : System.Multiprocessors.CPU_Range;
1179 Domain : Dispatching_Domain_Access;
1180 Task_Info : System.Task_Info.Task_Info_Type;
1181 Stack_Size : System.Parameters.Size_Type;
1182 T : Task_Id;
1183 Success : out Boolean);
1184 -- Initialize fields of the TCB for task T, and link into global TCB
1185 -- structures. Call this only with abort deferred and holding RTS_Lock.
1186 -- Self_ID is the calling task (normally the activator of T). Success is
1187 -- set to indicate whether the TCB was successfully initialized.
1188
1189 private
1190
1191 Null_Task : constant Task_Id := null;
1192
1193 type Activation_Chain is limited record
1194 T_ID : Task_Id;
1195 end record;
1196
1197 -- Activation_Chain is an in-out parameter of initialization procedures and
1198 -- it must be passed by reference because the init proc may terminate
1199 -- abnormally after creating task components, and these must be properly
1200 -- registered for removal (Expunge_Unactivated_Tasks). The "limited" forces
1201 -- Activation_Chain to be a by-reference type; see RM-6.2(4).
1202
1203 function Number_Of_Entries (Self_Id : Task_Id) return Entry_Index;
1204 -- Given a task, return the number of entries it contains
1205
1206 procedure Set_Entry_Names
1207 (Self_Id : Task_Id;
1208 Names : Task_Entry_Names_Access);
1209 -- Associate an array of strings denotinge entry [family] names with a task
1210
1211 end System.Tasking;