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