1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- S Y S T E M . T A S K I N G . S T A G E S --
9 -- Copyright (C) 1992-2008, Free Software Foundation, Inc. --
11 -- GNARL is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNARL; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
20 -- Boston, MA 02110-1301, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNARL was developed by the GNARL team at Florida State University. --
30 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
32 ------------------------------------------------------------------------------
34 -- This package represents the high level tasking interface used by the
35 -- compiler to expand Ada 95 tasking constructs into simpler run time calls
36 -- (aka GNARLI, GNU Ada Run-time Library Interface)
38 -- Note: Only the compiler is allowed to use this interface, by generating
39 -- direct calls to it, via Rtsfind.
41 -- Any changes to this interface may require corresponding compiler changes
42 -- in exp_ch9.adb and possibly exp_ch7.adb
44 with System
.Task_Info
;
45 with System
.Parameters
;
49 package System
.Tasking
.Stages
is
50 pragma Elaborate_Body
;
52 -- The compiler will expand in the GNAT tree the following construct:
54 -- task type T (Discr : Integer);
57 -- ...declarations, possibly some controlled...
68 -- _chain : aliased activation_chain;
69 -- activation_chainIP (_chain);
71 -- task type t (discr : integer);
72 -- tE : aliased boolean := false;
73 -- tZ : size_type := unspecified_size;
74 -- type tV (discr : integer) is limited record
75 -- _task_id : task_id;
77 -- procedure tB (_task : access tV);
79 -- procedure tVIP (_init : in out tV; _master : master_id;
80 -- _chain : in out activation_chain; _task_id : in task_image_type;
81 -- discr : integer) is
83 -- _init.discr := discr;
84 -- _init._task_id := null;
85 -- create_task (unspecified_priority, tZ,
86 -- unspecified_task_info, ada__real_time__time_span_zero, 0,
87 -- _master, task_procedure_access!(tB'address),
88 -- _init'address, tE'unchecked_access, _chain, _task_id, _init.
94 -- procedure tB (_task : access tV) is
95 -- discr : integer renames _task.discr;
97 -- procedure _clean is
101 -- finalize_list (F14b);
102 -- abort_undefer.all;
106 -- abort_undefer.all;
107 -- ...declarations...
108 -- complete_activation;
117 -- _master : constant master_id := current_master.all;
118 -- t1S : task_image_type := new string'"t1";
119 -- task_image_typeIP (t1, _master, _chain, t1S, 1);
121 -- activate_tasks (_chain'unchecked_access);
123 procedure Abort_Tasks
(Tasks
: Task_List
);
124 -- Compiler interface only. Do not call from within the RTS. Initiate
125 -- abort, however, the actual abort is done by abortee by means of
126 -- Abort_Handler and Abort_Undefer
131 -- abort_tasks (task_list'(t1._task_id, t2._task_id));
133 procedure Activate_Tasks
(Chain_Access
: Activation_Chain_Access
);
134 -- Compiler interface only. Do not call from within the RTS.
135 -- This must be called by the creator of a chain of one or more new tasks,
136 -- to activate them. The chain is a linked list that up to this point is
137 -- only known to the task that created them, though the individual tasks
138 -- are already in the All_Tasks_List.
140 -- The compiler builds the chain in LIFO order (as a stack). Another
141 -- version of this procedure had code to reverse the chain, so as to
142 -- activate the tasks in the order of declaration. This might be nice, but
143 -- it is not needed if priority-based scheduling is supported, since all
144 -- the activated tasks synchronize on the activators lock before they
145 -- start activating and so they should start activating in priority order.
146 -- ??? Actually, the body of this package DOES reverse the chain, so I
147 -- don't understand the above comment.
149 procedure Complete_Activation
;
150 -- Compiler interface only. Do not call from within the RTS.
151 -- This should be called from the task body at the end of
152 -- the elaboration code for its declarative part.
153 -- Decrement the count of tasks to be activated by the activator and
154 -- wake it up so it can check to see if all tasks have been activated.
155 -- Except for the environment task, which should never call this procedure,
156 -- T.Activator should only be null iff T has completed activation.
158 procedure Complete_Master
;
159 -- Compiler interface only. Do not call from within the RTS. This must
160 -- be called on exit from any master where Enter_Master was called.
161 -- Assume abort is deferred at this point.
163 procedure Complete_Task
;
164 -- Compiler interface only. Do not call from within the RTS.
165 -- This should be called from an implicit at-end handler
166 -- associated with the task body, when it completes.
167 -- From this point, the current task will become not callable.
168 -- If the current task have not completed activation, this should be done
169 -- now in order to wake up the activator (the environment task).
171 procedure Create_Task
173 Size
: System
.Parameters
.Size_Type
;
174 Task_Info
: System
.Task_Info
.Task_Info_Type
;
175 Relative_Deadline
: Ada
.Real_Time
.Time_Span
;
176 Num_Entries
: Task_Entry_Index
;
177 Master
: Master_Level
;
178 State
: Task_Procedure_Access
;
179 Discriminants
: System
.Address
;
180 Elaborated
: Access_Boolean
;
181 Chain
: in out Activation_Chain
;
183 Created_Task
: out Task_Id
;
184 Build_Entry_Names
: Boolean);
185 -- Compiler interface only. Do not call from within the RTS.
186 -- This must be called to create a new task.
188 -- Priority is the task's priority (assumed to be in the
189 -- System.Any_Priority'Range)
190 -- Size is the stack size of the task to create
191 -- Task_Info is the task info associated with the created task, or
192 -- Unspecified_Task_Info if none.
193 -- Relative_Deadline is the relative deadline associated with the created
194 -- task by means of a pragma Relative_Deadline, or 0.0 if none.
195 -- State is the compiler generated task's procedure body
196 -- Discriminants is a pointer to a limited record whose discriminants
197 -- are those of the task to create. This parameter should be passed as
198 -- the single argument to State.
199 -- Elaborated is a pointer to a Boolean that must be set to true on exit
200 -- if the task could be successfully elaborated.
201 -- Chain is a linked list of task that needs to be created. On exit,
202 -- Created_Task.Activation_Link will be Chain.T_ID, and Chain.T_ID
203 -- will be Created_Task (e.g the created task will be linked at the front
205 -- Task_Image is a string created by the compiler that the
206 -- run time can store to ease the debugging and the
207 -- Ada.Task_Identification facility.
208 -- Created_Task is the resulting task.
209 -- Build_Entry_Names is a flag which controls the allocation of the data
210 -- structure which stores all entry names.
212 -- This procedure can raise Storage_Error if the task creation failed.
214 function Current_Master
return Master_Level
;
215 -- Compiler interface only.
216 -- This is called to obtain the current master nesting level.
218 procedure Enter_Master
;
219 -- Compiler interface only. Do not call from within the RTS.
220 -- This must be called on entry to any "master" where a task,
221 -- or access type designating objects containing tasks, may be
224 procedure Expunge_Unactivated_Tasks
(Chain
: in out Activation_Chain
);
225 -- Compiler interface only. Do not call from within the RTS.
226 -- This must be called by the compiler-generated code for an allocator if
227 -- the allocated object contains tasks, if the allocator exits without
228 -- calling Activate_Tasks for a given activation chains, as can happen if
229 -- an exception occurs during initialization of the object.
231 -- This should be called ONLY for tasks created via an allocator. Recovery
232 -- of storage for unactivated local task declarations is done by
233 -- Complete_Master and Complete_Task.
235 -- We remove each task from Chain and All_Tasks_List before we free the
236 -- storage of its ATCB.
238 -- In other places where we recover the storage of unactivated tasks, we
239 -- need to clean out the entry queues, but here that should not be
240 -- necessary, since these tasks should not have been visible to any other
241 -- tasks, and so no task should be able to queue a call on their entries.
243 -- Just in case somebody misuses this subprogram, there is a check to
244 -- verify this condition.
246 procedure Finalize_Global_Tasks
;
247 -- This should be called to complete the execution of the environment task
248 -- and shut down the tasking runtime system. It is the equivalent of
249 -- Complete_Task, but for the environment task.
251 -- The environment task must first call Complete_Master, to wait for user
252 -- tasks that depend on library-level packages to terminate. It then calls
253 -- Abort_Dependents to abort the "independent" library-level server tasks
254 -- that are created implicitly by the RTS packages (signal and timer server
255 -- tasks), and then waits for them to terminate. Then, it calls
256 -- Vulnerable_Complete_Task.
258 -- It currently also executes the global finalization list, and then resets
261 procedure Free_Task
(T
: Task_Id
);
262 -- Recover all runtime system storage associated with the task T, but only
263 -- if T has terminated. Do nothing in the other case. It is called from
264 -- Unchecked_Deallocation, for objects that are or contain tasks.
266 procedure Move_Activation_Chain
267 (From
, To
: Activation_Chain_Access
;
268 New_Master
: Master_ID
);
269 -- Compiler interface only. Do not call from within the RTS.
270 -- Move all tasks on From list to To list, and change their Master_of_Task
271 -- to be New_Master. This is used to implement build-in-place function
272 -- returns. Tasks that are part of the return object are initially placed
273 -- on an activation chain local to the return statement, and their master
274 -- is the return statement, in case the return statement is left
275 -- prematurely (due to raising an exception, being aborted, or a goto or
276 -- exit statement). Once the return statement has completed successfully,
277 -- Move_Activation_Chain is called to move them to the caller's activation
278 -- chain, and change their master to the one passed in by the caller. If
279 -- that doesn't happen, they will never be activated, and will become
280 -- terminated on leaving the return statement.
282 procedure Set_Entry_Name
284 Pos
: Task_Entry_Index
;
285 Val
: String_Access
);
286 -- This is called by the compiler to map a string which denotes an entry
287 -- name to a task entry index.
289 function Terminated
(T
: Task_Id
) return Boolean;
290 -- This is called by the compiler to implement the 'Terminated attribute.
291 -- Though is not required to be so by the ARM, we choose to synchronize
292 -- with the task's ATCB, so that this is more useful for polling the state
293 -- of a task, and so that it becomes an abort completion point for the
294 -- calling task (via Undefer_Abort).
300 -- terminated (t1._task_id)
302 procedure Terminate_Task
(Self_ID
: Task_Id
);
303 -- Terminate the calling task.
304 -- This should only be called by the Task_Wrapper procedure, and to
305 -- deallocate storage associate with foreign tasks.
307 end System
.Tasking
.Stages
;