]>
Commit | Line | Data |
---|---|---|
cacbc350 RK |
1 | ------------------------------------------------------------------------------ |
2 | -- -- | |
3 | -- GNU ADA 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 | -- -- | |
8a6a52dc | 9 | -- Copyright (C) 1992-2004, Free Software Foundation, Inc. -- |
cacbc350 RK |
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 2, or (at your option) any later ver- -- | |
14 | -- sion. GNARL is distributed in the hope that it will be useful, but WITH- -- | |
15 | -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- | |
16 | -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -- | |
17 | -- for more details. You should have received a copy of the GNU General -- | |
18 | -- Public License distributed with GNARL; see file COPYING. If not, write -- | |
19 | -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, -- | |
20 | -- MA 02111-1307, USA. -- | |
21 | -- -- | |
22 | -- As a special exception, if other files instantiate generics from this -- | |
23 | -- unit, or you link this unit with other files to produce an executable, -- | |
24 | -- this unit does not by itself cause the resulting executable to be -- | |
25 | -- covered by the GNU General Public License. This exception does not -- | |
26 | -- however invalidate any other reasons why the executable file might be -- | |
27 | -- covered by the GNU Public License. -- | |
28 | -- -- | |
71ff80dc | 29 | -- GNARL was developed by the GNARL team at Florida State University. -- |
fbf5a39b | 30 | -- Extensive contributions were provided by Ada Core Technologies, Inc. -- |
cacbc350 RK |
31 | -- -- |
32 | ------------------------------------------------------------------------------ | |
33 | ||
34 | -- This package provides necessary type definitions for compiler interface. | |
35 | ||
36 | -- Note: the compiler generates direct calls to this interface, via Rtsfind. | |
37 | -- Any changes to this interface may require corresponding compiler changes. | |
38 | ||
39 | with Ada.Exceptions; | |
40 | -- Used for: Exception_Id | |
41 | ||
42 | with System.Parameters; | |
43 | -- used for Size_Type | |
44 | ||
45 | with System.Task_Info; | |
fbf5a39b | 46 | -- used for Task_Info_Type |
cacbc350 RK |
47 | |
48 | with System.Soft_Links; | |
49 | -- used for TSD | |
50 | ||
51 | with System.Task_Primitives; | |
52 | -- used for Private_Data | |
cacbc350 RK |
53 | |
54 | with Unchecked_Conversion; | |
55 | ||
56 | package System.Tasking is | |
57 | ||
15ce9ca2 AC |
58 | ------------------- |
59 | -- Locking Rules -- | |
60 | ------------------- | |
61 | ||
cacbc350 RK |
62 | -- The following rules must be followed at all times, to prevent |
63 | -- deadlock and generally ensure correct operation of locking. | |
15ce9ca2 | 64 | |
cacbc350 | 65 | -- . Never lock a lock unless abort is deferred. |
15ce9ca2 | 66 | |
cacbc350 | 67 | -- . Never undefer abort while holding a lock. |
15ce9ca2 | 68 | |
cacbc350 RK |
69 | -- . Overlapping critical sections must be properly nested, |
70 | -- and locks must be released in LIFO order. | |
71 | -- e.g., the following is not allowed: | |
15ce9ca2 | 72 | |
cacbc350 RK |
73 | -- Lock (X); |
74 | -- ... | |
75 | -- Lock (Y); | |
76 | -- ... | |
77 | -- Unlock (X); | |
78 | -- ... | |
79 | -- Unlock (Y); | |
15ce9ca2 | 80 | |
cacbc350 | 81 | -- Locks with lower (smaller) level number cannot be locked |
07fc65c4 | 82 | -- while holding a lock with a higher level number. (The level |
cacbc350 | 83 | -- number is the number at the left.) |
15ce9ca2 | 84 | |
cacbc350 RK |
85 | -- 1. System.Tasking.PO_Simple.Protection.L (any PO lock) |
86 | -- 2. System.Tasking.Initialization.Global_Task_Lock (in body) | |
07fc65c4 GB |
87 | -- 3. System.Task_Primitives.Operations.Single_RTS_Lock |
88 | -- 4. System.Tasking.Ada_Task_Control_Block.LL.L (any TCB lock) | |
15ce9ca2 | 89 | |
cacbc350 RK |
90 | -- Clearly, there can be no circular chain of hold-and-wait |
91 | -- relationships involving locks in different ordering levels. | |
15ce9ca2 | 92 | |
cacbc350 RK |
93 | -- We used to have Global_Task_Lock before Protection.L but this was |
94 | -- clearly wrong since there can be calls to "new" inside protected | |
95 | -- operations. The new ordering prevents these failures. | |
15ce9ca2 | 96 | |
07fc65c4 | 97 | -- Sometimes we need to hold two ATCB locks at the same time. To allow |
cacbc350 RK |
98 | -- us to order the locking, each ATCB is given a unique serial |
99 | -- number. If one needs to hold locks on several ATCBs at once, | |
100 | -- the locks with lower serial numbers must be locked first. | |
15ce9ca2 | 101 | |
cacbc350 RK |
102 | -- We don't always need to check the serial numbers, since |
103 | -- the serial numbers are assigned sequentially, and so: | |
15ce9ca2 | 104 | |
cacbc350 RK |
105 | -- . The parent of a task always has a lower serial number. |
106 | -- . The activator of a task always has a lower serial number. | |
107 | -- . The environment task has a lower serial number than any other task. | |
108 | -- . If the activator of a task is different from the task's parent, | |
109 | -- the parent always has a lower serial number than the activator. | |
cacbc350 RK |
110 | |
111 | --------------------------------- | |
b5e792e2 | 112 | -- Task_Id related definitions -- |
cacbc350 RK |
113 | --------------------------------- |
114 | ||
115 | type Ada_Task_Control_Block; | |
116 | ||
b5e792e2 | 117 | type Task_Id is access all Ada_Task_Control_Block; |
cacbc350 | 118 | |
b5e792e2 | 119 | Null_Task : constant Task_Id; |
cacbc350 | 120 | |
b5e792e2 | 121 | type Task_List is array (Positive range <>) of Task_Id; |
cacbc350 | 122 | |
b5e792e2 | 123 | function Self return Task_Id; |
cacbc350 RK |
124 | pragma Inline (Self); |
125 | -- This is the compiler interface version of this function. Do not call | |
126 | -- from the run-time system. | |
127 | ||
b5e792e2 AC |
128 | function To_Task_Id is new Unchecked_Conversion (System.Address, Task_Id); |
129 | function To_Address is new Unchecked_Conversion (Task_Id, System.Address); | |
cacbc350 RK |
130 | |
131 | ----------------------- | |
132 | -- Enumeration types -- | |
133 | ----------------------- | |
134 | ||
135 | type Task_States is | |
136 | (Unactivated, | |
137 | -- Task has been created but has not been activated. | |
138 | -- It cannot be executing. | |
139 | ||
140 | -- Active states | |
141 | -- For all states from here down, the task has been activated. | |
142 | -- For all states from here down, except for Terminated, the task | |
143 | -- may be executing. | |
144 | -- Activator = null iff it has not yet completed activating. | |
145 | ||
146 | -- For all states from here down, | |
147 | -- the task has been activated, and may be executing. | |
148 | ||
149 | Runnable, | |
150 | -- Task is not blocked for any reason known to Ada. | |
151 | -- (It may be waiting for a mutex, though.) | |
152 | -- It is conceptually "executing" in normal mode. | |
153 | ||
154 | Terminated, | |
155 | -- The task is terminated, in the sense of ARM 9.3 (5). | |
156 | -- Any dependents that were waiting on terminate | |
157 | -- alternatives have been awakened and have terminated themselves. | |
158 | ||
159 | Activator_Sleep, | |
160 | -- Task is waiting for created tasks to complete activation. | |
161 | ||
162 | Acceptor_Sleep, | |
163 | -- Task is waiting on an accept or selective wait statement. | |
164 | ||
165 | Entry_Caller_Sleep, | |
166 | -- Task is waiting on an entry call. | |
167 | ||
168 | Async_Select_Sleep, | |
169 | -- Task is waiting to start the abortable part of an | |
170 | -- asynchronous select statement. | |
171 | ||
172 | Delay_Sleep, | |
173 | -- Task is waiting on a select statement with only a delay | |
174 | -- alternative open. | |
175 | ||
176 | Master_Completion_Sleep, | |
177 | -- Master completion has two phases. | |
178 | -- In Phase 1 the task is sleeping in Complete_Master | |
179 | -- having completed a master within itself, | |
180 | -- and is waiting for the tasks dependent on that master to become | |
181 | -- terminated or waiting on a terminate Phase. | |
182 | ||
183 | Master_Phase_2_Sleep, | |
184 | -- In Phase 2 the task is sleeping in Complete_Master | |
185 | -- waiting for tasks on terminate alternatives to finish | |
186 | -- terminating. | |
187 | ||
188 | -- The following are special uses of sleep, for server tasks | |
189 | -- within the run-time system. | |
190 | ||
191 | Interrupt_Server_Idle_Sleep, | |
192 | Interrupt_Server_Blocked_Interrupt_Sleep, | |
193 | Timer_Server_Sleep, | |
194 | AST_Server_Sleep, | |
195 | ||
196 | Asynchronous_Hold, | |
197 | -- The task has been held by Asynchronous_Task_Control.Hold_Task | |
198 | ||
199 | Interrupt_Server_Blocked_On_Event_Flag | |
200 | -- The task has been blocked on a system call waiting for the | |
201 | -- completion event. | |
202 | ); | |
203 | ||
204 | type Call_Modes is | |
205 | (Simple_Call, Conditional_Call, Asynchronous_Call, Timed_Call); | |
206 | ||
207 | type Select_Modes is (Simple_Mode, Else_Mode, Terminate_Mode, Delay_Mode); | |
208 | ||
209 | subtype Delay_Modes is Integer; | |
210 | ||
211 | ------------------------------- | |
212 | -- Entry related definitions -- | |
213 | ------------------------------- | |
214 | ||
215 | Null_Entry : constant := 0; | |
216 | ||
217 | Max_Entry : constant := Integer'Last; | |
218 | ||
219 | Interrupt_Entry : constant := -2; | |
220 | ||
221 | Cancelled_Entry : constant := -1; | |
222 | ||
223 | type Entry_Index is range Interrupt_Entry .. Max_Entry; | |
224 | ||
225 | Null_Task_Entry : constant := Null_Entry; | |
226 | ||
227 | Max_Task_Entry : constant := Max_Entry; | |
228 | ||
229 | type Task_Entry_Index is new Entry_Index | |
230 | range Null_Task_Entry .. Max_Task_Entry; | |
231 | ||
232 | type Entry_Call_Record; | |
233 | ||
234 | type Entry_Call_Link is access all Entry_Call_Record; | |
235 | ||
236 | type Entry_Queue is record | |
237 | Head : Entry_Call_Link; | |
238 | Tail : Entry_Call_Link; | |
239 | end record; | |
240 | ||
241 | type Task_Entry_Queue_Array is | |
242 | array (Task_Entry_Index range <>) of Entry_Queue; | |
243 | ||
244 | ---------------------------------- | |
245 | -- Entry_Call_Record definition -- | |
246 | ---------------------------------- | |
247 | ||
248 | type Entry_Call_State is | |
249 | (Never_Abortable, | |
250 | -- the call is not abortable, and never can be | |
251 | ||
252 | Not_Yet_Abortable, | |
253 | -- the call is not abortable, but may become so | |
254 | ||
255 | Was_Abortable, | |
256 | -- the call is not abortable, but once was | |
257 | ||
258 | Now_Abortable, | |
259 | -- the call is abortable | |
260 | ||
261 | Done, | |
262 | -- the call has been completed | |
263 | ||
264 | Cancelled | |
265 | -- the call was asynchronous, and was cancelled | |
266 | ); | |
267 | ||
268 | -- Never_Abortable is used for calls that are made in a abort | |
269 | -- deferred region (see ARM 9.8(5-11), 9.8 (20)). | |
270 | -- Such a call is never abortable. | |
271 | ||
272 | -- The Was_ vs. Not_Yet_ distinction is needed to decide whether it | |
273 | -- is OK to advance into the abortable part of an async. select stmt. | |
274 | -- That is allowed iff the mode is Now_ or Was_. | |
275 | ||
276 | -- Done indicates the call has been completed, without cancellation, | |
277 | -- or no call has been made yet at this ATC nesting level, | |
278 | -- and so aborting the call is no longer an issue. | |
279 | -- Completion of the call does not necessarily indicate "success"; | |
280 | -- the call may be returning an exception if Exception_To_Raise is | |
281 | -- non-null. | |
282 | ||
283 | -- Cancelled indicates the call was cancelled, | |
284 | -- and so aborting the call is no longer an issue. | |
285 | ||
286 | -- The call is on an entry queue unless | |
287 | -- State >= Done, in which case it may or may not be still Onqueue. | |
288 | ||
289 | -- Please do not modify the order of the values, without checking | |
fbf5a39b | 290 | -- all uses of this type. We rely on partial "monotonicity" of |
cacbc350 | 291 | -- Entry_Call_Record.State to avoid locking when we access this |
fbf5a39b | 292 | -- value for certain tests. In particular: |
cacbc350 RK |
293 | |
294 | -- 1) Once State >= Done, we can rely that the call has been | |
fbf5a39b | 295 | -- completed. If State >= Done, it will not |
cacbc350 RK |
296 | -- change until the task does another entry call at this level. |
297 | ||
298 | -- 2) Once State >= Was_Abortable, we can rely that the call has | |
299 | -- been queued abortably at least once, and so the check for | |
300 | -- whether it is OK to advance to the abortable part of an | |
301 | -- async. select statement does not need to lock anything. | |
302 | ||
303 | type Restricted_Entry_Call_Record is record | |
b5e792e2 | 304 | Self : Task_Id; |
cacbc350 RK |
305 | -- ID of the caller |
306 | ||
307 | Mode : Call_Modes; | |
308 | ||
309 | State : Entry_Call_State; | |
310 | pragma Atomic (State); | |
311 | -- Indicates part of the state of the call. | |
312 | -- Protection: | |
313 | -- If the call is not on a queue, it should | |
314 | -- only be accessed by Self, and Self does not need any | |
315 | -- lock to modify this field. | |
316 | -- Once the call is on a queue, the value should be | |
317 | -- something other than Done unless it is cancelled, and access is | |
318 | -- controller by the "server" of the queue -- i.e., the lock | |
319 | -- of Checked_To_Protection (Call_Target) | |
320 | -- if the call record is on the queue of a PO, or the lock | |
321 | -- of Called_Target if the call is on the queue of a task. | |
322 | -- See comments on type declaration for more details. | |
323 | ||
324 | Uninterpreted_Data : System.Address; | |
325 | -- Data passed by the compiler. | |
326 | ||
327 | Exception_To_Raise : Ada.Exceptions.Exception_Id; | |
328 | -- The exception to raise once this call has been completed without | |
329 | -- being aborted. | |
330 | end record; | |
331 | pragma Suppress_Initialization (Restricted_Entry_Call_Record); | |
332 | ||
333 | ------------------------------------ | |
334 | -- Task related other definitions -- | |
335 | ------------------------------------ | |
336 | ||
337 | type Activation_Chain is limited private; | |
c885d7a1 | 338 | -- Comment required ??? |
cacbc350 RK |
339 | |
340 | type Activation_Chain_Access is access all Activation_Chain; | |
c885d7a1 | 341 | -- Comment required ??? |
cacbc350 RK |
342 | |
343 | type Task_Procedure_Access is access procedure (Arg : System.Address); | |
344 | ||
345 | type Access_Boolean is access all Boolean; | |
346 | ||
c885d7a1 AC |
347 | Detect_Blocking : constant Boolean; |
348 | -- Boolean constant set True iff Detect_Blocking is active | |
349 | ||
cacbc350 RK |
350 | ---------------------------------------------- |
351 | -- Ada_Task_Control_Block (ATCB) definition -- | |
352 | ---------------------------------------------- | |
353 | ||
354 | -- Notes on protection (synchronization) of TRTS data structures. | |
355 | ||
356 | -- Any field of the TCB can be written by the activator of a task when the | |
357 | -- task is created, since no other task can access the new task's | |
358 | -- state until creation is complete. | |
359 | ||
360 | -- The protection for each field is described in a comment starting with | |
361 | -- "Protection:". | |
362 | ||
363 | -- When a lock is used to protect an ATCB field, this lock is simply named. | |
364 | ||
365 | -- Some protection is described in terms of tasks related to the | |
366 | -- ATCB being protected. These are: | |
367 | ||
15ce9ca2 AC |
368 | -- Self: The task which is controlled by this ATCB |
369 | -- Acceptor: A task accepting a call from Self | |
370 | -- Caller: A task calling an entry of Self | |
371 | -- Parent: The task executing the master on which Self depends | |
372 | -- Dependent: A task dependent on Self | |
373 | -- Activator: The task that created Self and initiated its activation | |
374 | -- Created: A task created and activated by Self | |
cacbc350 RK |
375 | |
376 | -- Note: The order of the fields is important to implement efficiently | |
377 | -- tasking support under gdb. | |
378 | -- Currently gdb relies on the order of the State, Parent, Base_Priority, | |
fbf5a39b | 379 | -- Task_Image, Task_Image_Len, Call and LL fields. |
cacbc350 | 380 | |
15ce9ca2 AC |
381 | ------------------------- |
382 | -- Common ATCB section -- | |
383 | ------------------------- | |
384 | ||
385 | -- Section used by all GNARL implementations (regular and restricted) | |
cacbc350 RK |
386 | |
387 | type Common_ATCB is record | |
388 | State : Task_States; | |
389 | pragma Atomic (State); | |
390 | -- Encodes some basic information about the state of a task, | |
391 | -- including whether it has been activated, whether it is sleeping, | |
392 | -- and whether it is terminated. | |
393 | -- Protection: Self.L. | |
394 | ||
b5e792e2 | 395 | Parent : Task_Id; |
cacbc350 RK |
396 | -- The task on which this task depends. |
397 | -- See also Master_Level and Master_Within. | |
398 | ||
399 | Base_Priority : System.Any_Priority; | |
400 | -- Base priority, not changed during entry calls, only changed | |
401 | -- via dynamic priorities package. | |
402 | -- Protection: Only written by Self, accessed by anyone. | |
403 | ||
404 | Current_Priority : System.Any_Priority; | |
405 | -- Active priority, except that the effects of protected object | |
406 | -- priority ceilings are not reflected. This only reflects explicit | |
407 | -- priority changes and priority inherited through task activation | |
408 | -- and rendezvous. | |
409 | -- | |
410 | -- Ada 95 notes: In Ada 95, this field will be transferred to the | |
411 | -- Priority field of an Entry_Calls component when an entry call | |
412 | -- is initiated. The Priority of the Entry_Calls component will not | |
413 | -- change for the duration of the call. The accepting task can | |
414 | -- use it to boost its own priority without fear of its changing in | |
415 | -- the meantime. | |
416 | -- | |
417 | -- This can safely be used in the priority ordering | |
418 | -- of entry queues. Once a call is queued, its priority does not | |
419 | -- change. | |
420 | -- | |
421 | -- Since an entry call cannot be made while executing | |
422 | -- a protected action, the priority of a task will never reflect a | |
423 | -- priority ceiling change at the point of an entry call. | |
424 | -- | |
425 | -- Protection: Only written by Self, and only accessed when Acceptor | |
426 | -- accepts an entry or when Created activates, at which points Self is | |
427 | -- suspended. | |
428 | ||
c885d7a1 AC |
429 | Protected_Action_Nesting : Natural; |
430 | pragma Atomic (Protected_Action_Nesting); | |
431 | -- The dynamic level of protected action nesting for this task. | |
432 | -- This field is needed for checking whether potentially | |
433 | -- blocking operations are invoked from protected actions. | |
434 | -- pragma Atomic is used because it can be read/written from | |
435 | -- protected interrupt handlers. | |
436 | ||
fbf5a39b AC |
437 | Task_Image : String (1 .. 32); |
438 | -- Hold a string that provides a readable id for task, | |
cacbc350 RK |
439 | -- built from the variable of which it is a value or component. |
440 | ||
fbf5a39b AC |
441 | Task_Image_Len : Natural; |
442 | -- Actual length of Task_Image. | |
443 | ||
cacbc350 RK |
444 | Call : Entry_Call_Link; |
445 | -- The entry call that has been accepted by this task. | |
446 | -- Protection: Self.L. Self will modify this field | |
447 | -- when Self.Accepting is False, and will not need the mutex to do so. | |
448 | -- Once a task sets Pending_ATC_Level = 0, no other task can access | |
449 | -- this field. | |
450 | ||
451 | LL : aliased Task_Primitives.Private_Data; | |
452 | -- Control block used by the underlying low-level tasking | |
453 | -- service (GNULLI). | |
454 | -- Protection: This is used only by the GNULLI implementation, which | |
455 | -- takes care of all of its synchronization. | |
456 | ||
457 | Task_Arg : System.Address; | |
fbf5a39b AC |
458 | -- The argument to task procedure. Provide a handle for discriminant |
459 | -- information. | |
cacbc350 RK |
460 | -- Protection: Part of the synchronization between Self and |
461 | -- Activator. Activator writes it, once, before Self starts | |
462 | -- executing. Thereafter, Self only reads it. | |
463 | ||
464 | Task_Entry_Point : Task_Procedure_Access; | |
465 | -- Information needed to call the procedure containing the code for | |
466 | -- the body of this task. | |
467 | -- Protection: Part of the synchronization between Self and | |
468 | -- Activator. Activator writes it, once, before Self starts | |
469 | -- executing. Self reads it, once, as part of its execution. | |
470 | ||
471 | Compiler_Data : System.Soft_Links.TSD; | |
472 | -- Task-specific data needed by the compiler to store | |
473 | -- per-task structures. | |
474 | -- Protection: Only accessed by Self. | |
475 | ||
b5e792e2 | 476 | All_Tasks_Link : Task_Id; |
cacbc350 | 477 | -- Used to link this task to the list of all tasks in the system. |
07fc65c4 | 478 | -- Protection: RTS_Lock. |
cacbc350 | 479 | |
b5e792e2 | 480 | Activation_Link : Task_Id; |
cacbc350 RK |
481 | -- Used to link this task to a list of tasks to be activated. |
482 | -- Protection: Only used by Activator. | |
483 | ||
b5e792e2 | 484 | Activator : Task_Id; |
cacbc350 RK |
485 | -- The task that created this task, either by declaring it as a task |
486 | -- object or by executing a task allocator. | |
487 | -- The value is null iff Self has completed activation. | |
488 | -- Protection: Set by Activator before Self is activated, and | |
489 | -- only read and modified by Self after that. | |
490 | ||
491 | Wait_Count : Integer; | |
492 | -- This count is used by a task that is waiting for other tasks. | |
493 | -- At all other times, the value should be zero. | |
494 | -- It is used differently in several different states. | |
495 | -- Since a task cannot be in more than one of these states at the | |
496 | -- same time, a single counter suffices. | |
497 | -- Protection: Self.L. | |
498 | ||
499 | -- Activator_Sleep | |
500 | ||
501 | -- This is the number of tasks that this task is activating, i.e. the | |
502 | -- children that have started activation but have not completed it. | |
503 | -- Protection: Self.L and Created.L. Both mutexes must be locked, | |
504 | -- since Self.Activation_Count and Created.State must be synchronized. | |
505 | ||
506 | -- Master_Completion_Sleep (phase 1) | |
507 | ||
508 | -- This is the number dependent tasks of a master being | |
509 | -- completed by Self that are not activated, not terminated, and | |
510 | -- not waiting on a terminate alternative. | |
511 | ||
512 | -- Master_Completion_2_Sleep (phase 2) | |
513 | ||
514 | -- This is the count of tasks dependent on a master being | |
515 | -- completed by Self which are waiting on a terminate alternative. | |
516 | ||
517 | Elaborated : Access_Boolean; | |
518 | -- Pointer to a flag indicating that this task's body has been | |
519 | -- elaborated. The flag is created and managed by the | |
520 | -- compiler-generated code. | |
521 | -- Protection: The field itself is only accessed by Activator. The flag | |
522 | -- that it points to is updated by Master and read by Activator; access | |
523 | -- is assumed to be atomic. | |
524 | ||
525 | Activation_Failed : Boolean; | |
526 | -- Set to True if activation of a chain of tasks fails, | |
527 | -- so that the activator should raise Tasking_Error. | |
528 | ||
529 | Task_Info : System.Task_Info.Task_Info_Type; | |
530 | -- System-specific attributes of the task as specified by the | |
531 | -- Task_Info pragma. | |
532 | end record; | |
533 | ||
534 | --------------------------------------- | |
535 | -- Restricted_Ada_Task_Control_Block -- | |
536 | --------------------------------------- | |
537 | ||
538 | -- This type should only be used by the restricted GNARLI and by | |
539 | -- restricted GNULL implementations to allocate an ATCB (see | |
540 | -- System.Task_Primitives.Operations.New_ATCB) that will take | |
541 | -- significantly less memory. | |
542 | -- Note that the restricted GNARLI should only access fields that are | |
543 | -- present in the Restricted_Ada_Task_Control_Block structure. | |
544 | ||
545 | type Restricted_Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is | |
546 | record | |
547 | Common : Common_ATCB; | |
548 | -- The common part between various tasking implementations | |
549 | ||
550 | Entry_Call : aliased Restricted_Entry_Call_Record; | |
551 | -- Protection: This field is used on entry call "queues" associated | |
552 | -- with protected objects, and is protected by the protected object | |
553 | -- lock. | |
554 | end record; | |
555 | pragma Suppress_Initialization (Restricted_Ada_Task_Control_Block); | |
556 | ||
b5e792e2 | 557 | Interrupt_Manager_ID : Task_Id; |
cacbc350 | 558 | -- This task ID is declared here to break circular dependencies. |
b5e792e2 | 559 | -- Also declare Interrupt_Manager_ID after Task_Id is known, to avoid |
cacbc350 RK |
560 | -- generating unneeded finalization code. |
561 | ||
562 | ----------------------- | |
563 | -- List of all Tasks -- | |
564 | ----------------------- | |
565 | ||
b5e792e2 | 566 | All_Tasks_List : Task_Id; |
cacbc350 RK |
567 | -- Global linked list of all tasks. |
568 | ||
569 | ------------------------------------------ | |
570 | -- Regular (non restricted) definitions -- | |
571 | ------------------------------------------ | |
572 | ||
573 | -------------------------------- | |
574 | -- Master Related Definitions -- | |
575 | -------------------------------- | |
576 | ||
577 | subtype Master_Level is Integer; | |
578 | subtype Master_ID is Master_Level; | |
579 | ||
580 | -- Normally, a task starts out with internal master nesting level | |
581 | -- one larger than external master nesting level. It is incremented | |
582 | -- to one by Enter_Master, which is called in the task body only if | |
583 | -- the compiler thinks the task may have dependent tasks. It is set to 1 | |
584 | -- for the environment task, the level 2 is reserved for server tasks of | |
585 | -- the run-time system (the so called "independent tasks"), and the level | |
586 | -- 3 is for the library level tasks. | |
587 | ||
588 | Environment_Task_Level : constant Master_Level := 1; | |
589 | Independent_Task_Level : constant Master_Level := 2; | |
590 | Library_Task_Level : constant Master_Level := 3; | |
591 | ||
592 | ------------------------------ | |
593 | -- Task size, priority info -- | |
594 | ------------------------------ | |
595 | ||
596 | Unspecified_Priority : constant Integer := System.Priority'First - 1; | |
597 | ||
598 | Priority_Not_Boosted : constant Integer := System.Priority'First - 1; | |
599 | -- Definition of Priority actually has to come from the RTS configuration. | |
600 | ||
601 | subtype Rendezvous_Priority is Integer | |
602 | range Priority_Not_Boosted .. System.Any_Priority'Last; | |
603 | ||
604 | ------------------------------------ | |
605 | -- Rendezvous related definitions -- | |
606 | ------------------------------------ | |
607 | ||
608 | No_Rendezvous : constant := 0; | |
609 | ||
610 | Max_Select : constant Integer := Integer'Last; | |
611 | -- RTS-defined | |
612 | ||
613 | subtype Select_Index is Integer range No_Rendezvous .. Max_Select; | |
614 | -- type Select_Index is range No_Rendezvous .. Max_Select; | |
615 | ||
616 | subtype Positive_Select_Index is | |
617 | Select_Index range 1 .. Select_Index'Last; | |
618 | ||
619 | type Accept_Alternative is record | |
620 | Null_Body : Boolean; | |
621 | S : Task_Entry_Index; | |
622 | end record; | |
623 | ||
624 | type Accept_List is | |
625 | array (Positive_Select_Index range <>) of Accept_Alternative; | |
626 | ||
627 | type Accept_List_Access is access constant Accept_List; | |
628 | ||
629 | ----------------------------------- | |
630 | -- ATC_Level related definitions -- | |
631 | ----------------------------------- | |
632 | ||
633 | Max_ATC_Nesting : constant Natural := 20; | |
634 | ||
635 | subtype ATC_Level_Base is Integer range 0 .. Max_ATC_Nesting; | |
636 | ||
637 | ATC_Level_Infinity : constant ATC_Level_Base := ATC_Level_Base'Last; | |
638 | ||
639 | subtype ATC_Level is ATC_Level_Base range 0 .. ATC_Level_Base'Last - 1; | |
640 | ||
641 | subtype ATC_Level_Index is ATC_Level range 1 .. ATC_Level'Last; | |
642 | ||
643 | ---------------------------------- | |
644 | -- Entry_Call_Record definition -- | |
645 | ---------------------------------- | |
646 | ||
647 | type Entry_Call_Record is record | |
b5e792e2 | 648 | Self : Task_Id; |
cacbc350 RK |
649 | -- ID of the caller |
650 | ||
651 | Mode : Call_Modes; | |
652 | ||
653 | State : Entry_Call_State; | |
654 | pragma Atomic (State); | |
655 | -- Indicates part of the state of the call. | |
656 | -- Protection: | |
657 | -- If the call is not on a queue, it should | |
658 | -- only be accessed by Self, and Self does not need any | |
659 | -- lock to modify this field. | |
660 | -- Once the call is on a queue, the value should be | |
661 | -- something other than Done unless it is cancelled, and access is | |
662 | -- controller by the "server" of the queue -- i.e., the lock | |
663 | -- of Checked_To_Protection (Call_Target) | |
664 | -- if the call record is on the queue of a PO, or the lock | |
665 | -- of Called_Target if the call is on the queue of a task. | |
666 | -- See comments on type declaration for more details. | |
667 | ||
668 | Uninterpreted_Data : System.Address; | |
669 | -- Data passed by the compiler. | |
670 | ||
671 | Exception_To_Raise : Ada.Exceptions.Exception_Id; | |
672 | -- The exception to raise once this call has been completed without | |
673 | -- being aborted. | |
674 | ||
675 | Prev : Entry_Call_Link; | |
676 | ||
677 | Next : Entry_Call_Link; | |
678 | ||
679 | Level : ATC_Level; | |
680 | -- One of Self and Level are redundant in this implementation, since | |
681 | -- each Entry_Call_Record is at Self.Entry_Calls (Level). Since we must | |
682 | -- have access to the entry call record to be reading this, we could | |
683 | -- get Self from Level, or Level from Self. However, this requires | |
684 | -- non-portable address arithmetic. | |
685 | ||
686 | E : Entry_Index; | |
687 | ||
688 | Prio : System.Any_Priority; | |
689 | ||
690 | -- The above fields are those that there may be some hope of packing. | |
691 | -- They are gathered together to allow for compilers that lay records | |
692 | -- out contiguously, to allow for such packing. | |
693 | ||
b5e792e2 | 694 | Called_Task : Task_Id; |
cacbc350 RK |
695 | pragma Atomic (Called_Task); |
696 | -- Use for task entry calls. | |
697 | -- The value is null if the call record is not in use. | |
698 | -- Conversely, unless State is Done and Onqueue is false, | |
699 | -- Called_Task points to an ATCB. | |
700 | -- Protection: Called_Task.L. | |
701 | ||
702 | Called_PO : System.Address; | |
703 | pragma Atomic (Called_PO); | |
704 | -- Similar to Called_Task but for protected objects. | |
705 | -- Note that the previous implementation tried to merge both | |
706 | -- Called_Task and Called_PO but this ended up in many unexpected | |
707 | -- complications (e.g having to add a magic number in the ATCB, which | |
708 | -- caused gdb lots of confusion) with no real gain since the Lock_Server | |
709 | -- implementation still need to loop around chasing for pointer changes | |
710 | -- even with a single pointer. | |
711 | ||
712 | Acceptor_Prev_Call : Entry_Call_Link; | |
713 | -- For task entry calls only. | |
714 | ||
715 | Acceptor_Prev_Priority : Rendezvous_Priority := Priority_Not_Boosted; | |
716 | -- For task entry calls only. | |
717 | -- The priority of the most recent prior call being serviced. | |
718 | -- For protected entry calls, this function should be performed by | |
719 | -- GNULLI ceiling locking. | |
720 | ||
721 | Cancellation_Attempted : Boolean := False; | |
722 | pragma Atomic (Cancellation_Attempted); | |
723 | -- Cancellation of the call has been attempted. | |
724 | -- If it has succeeded, State = Cancelled. | |
725 | -- ????? | |
726 | -- Consider merging this into State? | |
727 | ||
728 | Requeue_With_Abort : Boolean := False; | |
729 | -- Temporary to tell caller whether requeue is with abort. | |
730 | -- ????? | |
731 | -- Find a better way of doing this. | |
732 | ||
733 | Needs_Requeue : Boolean := False; | |
734 | -- Temporary to tell acceptor of task entry call that | |
735 | -- Exceptional_Complete_Rendezvous needs to do requeue. | |
736 | end record; | |
737 | ||
738 | ------------------------------------ | |
739 | -- Task related other definitions -- | |
740 | ------------------------------------ | |
741 | ||
742 | type Access_Address is access all System.Address; | |
8a6a52dc AC |
743 | -- Comment on what this is used for ??? |
744 | ||
745 | pragma No_Strict_Aliasing (Access_Address); | |
746 | -- This type is used in contexts where aliasing may be an issue (see | |
747 | -- for example s-tataat.adb), so we avoid any incorrect aliasing | |
748 | -- assumptions. | |
cacbc350 RK |
749 | |
750 | ---------------------------------------------- | |
751 | -- Ada_Task_Control_Block (ATCB) definition -- | |
752 | ---------------------------------------------- | |
753 | ||
754 | type Entry_Call_Array is array (ATC_Level_Index) of | |
755 | aliased Entry_Call_Record; | |
756 | ||
fbf5a39b AC |
757 | type Direct_Index is range 0 .. Parameters.Default_Attribute_Count; |
758 | subtype Direct_Index_Range is Direct_Index range 1 .. Direct_Index'Last; | |
cacbc350 | 759 | -- Attributes with indices in this range are stored directly in |
fbf5a39b | 760 | -- the task control block. Such attributes must be Address-sized. |
cacbc350 RK |
761 | -- Other attributes will be held in dynamically allocated records |
762 | -- chained off of the task control block. | |
763 | ||
fbf5a39b AC |
764 | type Direct_Attribute_Element is mod Memory_Size; |
765 | pragma Atomic (Direct_Attribute_Element); | |
766 | ||
cacbc350 | 767 | type Direct_Attribute_Array is |
fbf5a39b | 768 | array (Direct_Index_Range) of aliased Direct_Attribute_Element; |
cacbc350 | 769 | |
fbf5a39b | 770 | type Direct_Index_Vector is mod 2 ** Parameters.Default_Attribute_Count; |
cacbc350 RK |
771 | -- This is a bit-vector type, used to store information about |
772 | -- the usage of the direct attribute fields. | |
773 | ||
774 | type Task_Serial_Number is mod 2 ** 64; | |
775 | -- Used to give each task a unique serial number. | |
776 | ||
777 | type Ada_Task_Control_Block (Entry_Num : Task_Entry_Index) is record | |
778 | Common : Common_ATCB; | |
779 | -- The common part between various tasking implementations | |
780 | ||
781 | Entry_Calls : Entry_Call_Array; | |
782 | -- An array of entry calls. | |
783 | -- Protection: The elements of this array are on entry call queues | |
784 | -- associated with protected objects or task entries, and are protected | |
785 | -- by the protected object lock or Acceptor.L, respectively. | |
786 | ||
787 | New_Base_Priority : System.Any_Priority; | |
788 | -- New value for Base_Priority (for dynamic priorities package). | |
789 | -- Protection: Self.L. | |
790 | ||
791 | Global_Task_Lock_Nesting : Natural := 0; | |
792 | -- This is the current nesting level of calls to | |
793 | -- System.Tasking.Stages.Lock_Task_T. | |
794 | -- This allows a task to call Lock_Task_T multiple times without | |
795 | -- deadlocking. A task only locks All_Task_Lock when its | |
796 | -- All_Tasks_Nesting goes from 0 to 1, and only unlocked when it | |
797 | -- goes from 1 to 0. | |
798 | -- Protection: Only accessed by Self. | |
799 | ||
800 | Open_Accepts : Accept_List_Access; | |
801 | -- This points to the Open_Accepts array of accept alternatives passed | |
802 | -- to the RTS by the compiler-generated code to Selective_Wait. | |
803 | -- It is non-null iff this task is ready to accept an entry call. | |
804 | -- Protection: Self.L. | |
805 | ||
806 | Chosen_Index : Select_Index; | |
807 | -- The index in Open_Accepts of the entry call accepted by a selective | |
808 | -- wait executed by this task. | |
809 | -- Protection: Written by both Self and Caller. Usually protected | |
810 | -- by Self.L. However, once the selection is known to have been | |
811 | -- written it can be accessed without protection. This happens | |
812 | -- after Self has updated it itself using information from a suspended | |
813 | -- Caller, or after Caller has updated it and awakened Self. | |
814 | ||
815 | Master_of_Task : Master_Level; | |
816 | -- The task executing the master of this task, and the ID of this task's | |
817 | -- master (unique only among masters currently active within Parent). | |
818 | -- Protection: Set by Activator before Self is activated, and | |
819 | -- read after Self is activated. | |
820 | ||
821 | Master_Within : Master_Level; | |
822 | -- The ID of the master currently executing within this task; that is, | |
823 | -- the most deeply nested currently active master. | |
824 | -- Protection: Only written by Self, and only read by Self or by | |
825 | -- dependents when Self is attempting to exit a master. Since Self | |
826 | -- will not write this field until the master is complete, the | |
827 | -- synchronization should be adequate to prevent races. | |
828 | ||
829 | Alive_Count : Integer := 0; | |
830 | -- Number of tasks directly dependent on this task (including itself) | |
831 | -- that are still "alive", i.e. not terminated. | |
832 | -- Protection: Self.L. | |
833 | ||
834 | Awake_Count : Integer := 0; | |
835 | -- Number of tasks directly dependent on this task (including itself) | |
836 | -- still "awake", i.e., are not terminated and not waiting on a | |
837 | -- terminate alternative. | |
838 | -- Invariant: Awake_Count <= Alive_Count | |
839 | -- Protection: Self.L. | |
840 | ||
841 | -- beginning of flags | |
842 | ||
843 | Aborting : Boolean := False; | |
844 | pragma Atomic (Aborting); | |
845 | -- Self is in the process of aborting. While set, prevents multiple | |
846 | -- abortion signals from being sent by different aborter while abortion | |
847 | -- is acted upon. This is essential since an aborter which calls | |
848 | -- Abort_To_Level could set the Pending_ATC_Level to yet a lower level | |
849 | -- (than the current level), may be preempted and would send the | |
850 | -- abortion signal when resuming execution. At this point, the abortee | |
851 | -- may have completed abortion to the proper level such that the | |
852 | -- signal (and resulting abortion exception) are not handled any more. | |
853 | -- In other words, the flag prevents a race between multiple aborters | |
854 | -- and the abortee. | |
fbf5a39b | 855 | -- Protection: protected by atomic access. |
cacbc350 RK |
856 | |
857 | ATC_Hack : Boolean := False; | |
858 | pragma Atomic (ATC_Hack); | |
859 | -- ????? | |
860 | -- Temporary fix, to allow Undefer_Abort to reset Aborting in the | |
861 | -- handler for Abort_Signal that encloses an async. entry call. | |
862 | -- For the longer term, this should be done via code in the | |
863 | -- handler itself. | |
864 | ||
865 | Callable : Boolean := True; | |
866 | -- It is OK to call entries of this task. | |
867 | ||
868 | Dependents_Aborted : Boolean := False; | |
869 | -- This is set to True by whichever task takes responsibility | |
870 | -- for aborting the dependents of this task. | |
871 | -- Protection: Self.L. | |
872 | ||
873 | Interrupt_Entry : Boolean := False; | |
874 | -- Indicates if one or more Interrupt Entries are attached to | |
875 | -- the task. This flag is needed for cleaning up the Interrupt | |
876 | -- Entry bindings. | |
877 | ||
878 | Pending_Action : Boolean := False; | |
879 | -- Unified flag indicating some action needs to be take when abort | |
fbf5a39b | 880 | -- next becomes undeferred. Currently set if: |
cacbc350 RK |
881 | -- . Pending_Priority_Change is set |
882 | -- . Pending_ATC_Level is changed | |
883 | -- . Requeue involving POs | |
884 | -- (Abortable field may have changed and the Wait_Until_Abortable | |
885 | -- has to recheck the abortable status of the call.) | |
886 | -- . Exception_To_Raise is non-null | |
887 | -- Protection: Self.L. | |
888 | -- This should never be reset back to False outside of the | |
889 | -- procedure Do_Pending_Action, which is called by Undefer_Abort. | |
890 | -- It should only be set to True by Set_Priority and Abort_To_Level. | |
891 | ||
892 | Pending_Priority_Change : Boolean := False; | |
893 | -- Flag to indicate pending priority change (for dynamic priorities | |
894 | -- package). The base priority is updated on the next abortion | |
895 | -- completion point (aka. synchronization point). | |
896 | -- Protection: Self.L. | |
897 | ||
898 | Terminate_Alternative : Boolean := False; | |
899 | -- Task is accepting Select with Terminate Alternative. | |
900 | -- Protection: Self.L. | |
901 | ||
902 | -- end of flags | |
903 | ||
904 | -- beginning of counts | |
905 | ||
906 | ATC_Nesting_Level : ATC_Level := 1; | |
907 | -- The dynamic level of ATC nesting (currently executing nested | |
908 | -- asynchronous select statements) in this task. | |
909 | -- Protection: Self_ID.L. | |
910 | -- Only Self reads or updates this field. | |
911 | -- Decrementing it deallocates an Entry_Calls component, and care must | |
912 | -- be taken that all references to that component are eliminated | |
913 | -- before doing the decrement. This in turn will require locking | |
914 | -- a protected object (for a protected entry call) or the Acceptor's | |
915 | -- lock (for a task entry call). | |
916 | -- No other task should attempt to read or modify this value. | |
917 | ||
918 | Deferral_Level : Natural := 1; | |
919 | -- This is the number of times that Defer_Abortion has been called by | |
920 | -- this task without a matching Undefer_Abortion call. Abortion is | |
921 | -- only allowed when this zero. | |
922 | -- It is initially 1, to protect the task at startup. | |
923 | -- Protection: Only updated by Self; access assumed to be atomic. | |
924 | ||
925 | Pending_ATC_Level : ATC_Level_Base := ATC_Level_Infinity; | |
926 | -- The ATC level to which this task is currently being aborted. | |
927 | -- If the value is zero, the entire task has "completed". | |
928 | -- That may be via abort, exception propagation, or normal exit. | |
929 | -- If the value is ATC_Level_Infinity, the task is not being | |
930 | -- aborted to any level. | |
931 | -- If the value is positive, the task has not completed. | |
932 | -- This should ONLY be modified by | |
933 | -- Abort_To_Level and Exit_One_ATC_Level. | |
934 | -- Protection: Self.L. | |
935 | ||
936 | Serial_Number : Task_Serial_Number; | |
937 | -- A growing number to provide some way to check locking | |
938 | -- rules/ordering. | |
939 | ||
940 | Known_Tasks_Index : Integer := -1; | |
941 | -- Index in the System.Tasking.Debug.Known_Tasks array. | |
942 | ||
fbf5a39b AC |
943 | User_State : Long_Integer := 0; |
944 | -- User-writeable location, for use in debugging tasks; | |
945 | -- also provides a simple task specific data. | |
cacbc350 RK |
946 | |
947 | Direct_Attributes : Direct_Attribute_Array; | |
07fc65c4 GB |
948 | -- For task attributes that have same size as Address |
949 | ||
cacbc350 | 950 | Is_Defined : Direct_Index_Vector := 0; |
07fc65c4 GB |
951 | -- Bit I is 1 iff Direct_Attributes (I) is defined |
952 | ||
cacbc350 | 953 | Indirect_Attributes : Access_Address; |
07fc65c4 | 954 | -- A pointer to chain of records for other attributes that |
cacbc350 RK |
955 | -- are not address-sized, including all tagged types. |
956 | ||
957 | Entry_Queues : Task_Entry_Queue_Array (1 .. Entry_Num); | |
958 | -- An array of task entry queues. | |
959 | -- Protection: Self.L. Once a task has set Self.Stage to Completing, it | |
960 | -- has exclusive access to this field. | |
961 | end record; | |
cacbc350 RK |
962 | |
963 | --------------------- | |
964 | -- Initialize_ATCB -- | |
965 | --------------------- | |
966 | ||
967 | procedure Initialize_ATCB | |
b5e792e2 | 968 | (Self_ID : Task_Id; |
cacbc350 RK |
969 | Task_Entry_Point : Task_Procedure_Access; |
970 | Task_Arg : System.Address; | |
b5e792e2 | 971 | Parent : Task_Id; |
cacbc350 RK |
972 | Elaborated : Access_Boolean; |
973 | Base_Priority : System.Any_Priority; | |
974 | Task_Info : System.Task_Info.Task_Info_Type; | |
975 | Stack_Size : System.Parameters.Size_Type; | |
523456db | 976 | T : Task_Id; |
cacbc350 RK |
977 | Success : out Boolean); |
978 | -- Initialize fields of a TCB and link into global TCB structures | |
07fc65c4 | 979 | -- Call this only with abort deferred and holding RTS_Lock. |
523456db | 980 | -- Need more documentation, mention T, and describe Success ??? |
cacbc350 RK |
981 | |
982 | private | |
b5e792e2 | 983 | Null_Task : constant Task_Id := null; |
cacbc350 | 984 | |
c885d7a1 AC |
985 | GL_Detect_Blocking : Integer; |
986 | pragma Import (C, GL_Detect_Blocking, "__gl_detect_blocking"); | |
987 | -- Global variable exported by the binder generated file. A value | |
988 | -- equal to 1 indicates that pragma Detect_Blocking is active, | |
989 | -- while 0 is used for the pragma not being present. | |
990 | ||
991 | Detect_Blocking : constant Boolean := GL_Detect_Blocking = 1; | |
992 | ||
cacbc350 | 993 | type Activation_Chain is record |
b5e792e2 | 994 | T_ID : Task_Id; |
cacbc350 RK |
995 | end record; |
996 | pragma Volatile (Activation_Chain); | |
997 | ||
998 | -- Activation_chain is an in-out parameter of initialization procedures | |
fbf5a39b | 999 | -- and it must be passed by reference because the init proc may terminate |
cacbc350 RK |
1000 | -- abnormally after creating task components, and these must be properly |
1001 | -- registered for removal (Expunge_Unactivated_Tasks). | |
1002 | ||
1003 | end System.Tasking; |