1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT COMPILER COMPONENTS                         --
4--                                                                          --
5--                     S Y S T E M . T A S K _ I N F O                      --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--          Copyright (C) 1992-2003 Free Software Foundation, Inc.          --
10--                                                                          --
11-- GNAT 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.  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.  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 GNAT;  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--                                                                          --
29-- GNAT was originally developed  by the GNAT team at  New York University. --
30-- Extensive contributions were provided by Ada Core Technologies Inc.      --
31--                                                                          --
32------------------------------------------------------------------------------
33
34--  This package contains the definitions and routines associated with the
35--  implementation and use of the Task_Info pragma. It is specialized
36--  appropriately for targets that make use of this pragma.
37
38--  Note: the compiler generates direct calls to this interface, via Rtsfind.
39--  Any changes to this interface may require corresponding compiler changes.
40
41--  This unit may be used directly from an application program by providing
42--  an appropriate WITH, and the interface can be expected to remain stable.
43
44--  This is the SGI (libathread) specific version of this module.
45
46with System.OS_Interface;
47
48package System.Task_Info is
49   pragma Elaborate_Body;
50   --  To ensure that a body is allowed
51
52   ---------------------------------------------------------
53   -- Binding of Tasks to sprocs and sprocs to processors --
54   ---------------------------------------------------------
55
56   --  The SGI implementation of the GNU Low-Level Interface (GNULLI)
57   --  implements each Ada task as a Posix thread (Pthread). The SGI
58   --  Pthread library distributes threads across one or more processes
59   --  that are members of a common share group. Irix distributes
60   --  processes across the available CPUs on a given machine. The
61   --  pragma Task_Info provides the mechanism to control the distribution
62   --  of tasks to sprocs, and sprocs to processors.
63
64   --  Each thread has a number of attributes that dictate it's scheduling.
65   --  These attributes are:
66   --
67   --      Bound_To_Sproc:  whether the thread is bound to a specific sproc
68   --                       for its entire lifetime.
69   --
70   --      Timeslice:       Amount of time that a thread is allowed to execute
71   --                       before the system yeilds control to another thread
72   --                       of equal priority.
73   --
74   --      Resource_Vector: A bitmask used to control the binding of threads
75   --                       to sprocs.
76   --
77
78   --  Each share group process (sproc)
79
80   --  The Task_Info pragma:
81
82   --    pragma Task_Info (EXPRESSION);
83
84   --  allows the specification on a task by task basis of a value of type
85   --  System.Task_Info.Task_Info_Type to be passed to a task when it is
86   --  created. The specification of this type, and the effect on the task
87   --  that is created is target dependent.
88
89   --  The Task_Info pragma appears within a task definition (compare the
90   --  definition and implementation of pragma Priority). If no such pragma
91   --  appears, then the value Task_Info_Unspecified is passed. If a pragma
92   --  is present, then it supplies an alternative value. If the argument of
93   --  the pragma is a discriminant reference, then the value can be set on
94   --  a task by task basis by supplying the appropriate discriminant value.
95
96   --  Note that this means that the type used for Task_Info_Type must be
97   --  suitable for use as a discriminant (i.e. a scalar or access type).
98
99   ----------------------
100   -- Resource Vectors --
101   ----------------------
102
103   --  <discussion>
104
105   type Resource_Vector_T is array (0 .. 31) of Boolean;
106   pragma Pack (Resource_Vector_T);
107
108   NO_RESOURCES : constant Resource_Vector_T := (others => False);
109
110   generic
111      type Resource_T is (<>);
112      --  Discrete type up to 32 entries
113
114   package Resource_Vector_Functions is
115      function "+"
116        (R    : Resource_T)
117         return Resource_Vector_T;
118
119      function "+"
120        (R1   : Resource_T;
121         R2   : Resource_T)
122         return Resource_Vector_T;
123
124      function "+"
125        (R    : Resource_T;
126         S    : Resource_Vector_T)
127         return Resource_Vector_T;
128
129      function "+"
130        (S    : Resource_Vector_T;
131         R    : Resource_T)
132         return Resource_Vector_T;
133
134      function "+"
135        (S1   : Resource_Vector_T;
136         S2   : Resource_Vector_T)
137         return Resource_Vector_T;
138
139      function "-"
140        (S    : Resource_Vector_T;
141         R    : Resource_T)
142         return Resource_Vector_T;
143   end Resource_Vector_Functions;
144
145   ----------------------
146   -- Sproc Attributes --
147   ----------------------
148
149   subtype sproc_t is System.OS_Interface.sproc_t;
150
151   subtype CPU_Number is Integer range -1 .. Integer'Last;
152
153   ANY_CPU : constant CPU_Number := CPU_Number'First;
154
155   type Non_Degrading_Priority is range 0 .. 255;
156   --  Specification of IRIX Non Degrading Priorities.
157   --
158   --  WARNING: IRIX priorities have the reverse meaning of Ada priorities.
159   --           The lower the priority value, the greater the greater the
160   --           scheduling preference.
161   --
162   --  See the schedctl(2) man page for a complete discussion of non-degrading
163   --  priorities.
164
165   NDPHIMAX : constant Non_Degrading_Priority := 30;
166   NDPHIMIN : constant Non_Degrading_Priority := 39;
167   --  These priorities are higher than ALL normal user process priorities
168
169   subtype NDP_High is Non_Degrading_Priority range NDPHIMAX .. NDPHIMIN;
170
171   NDPNORMMAX : constant Non_Degrading_Priority := 40;
172   NDPNORMMIN : constant Non_Degrading_Priority := 127;
173   --  These priorities overlap normal user process priorities
174
175   subtype NDP_Norm is Non_Degrading_Priority range NDPNORMMAX .. NDPNORMMIN;
176
177   NDPLOMAX : constant Non_Degrading_Priority := 128;
178   NDPLOMIN : constant Non_Degrading_Priority := 254;
179   --  These priorities are below ALL normal user process priorities
180
181   NDP_NONE   : constant Non_Degrading_Priority := 255;
182
183   subtype NDP_LOW is Non_Degrading_Priority range NDPLOMAX .. NDPLOMIN;
184
185   type Page_Locking is
186      (NOLOCK,     --  Do not lock pages in memory
187       PROCLOCK,   --  Lock text and data segments into memory (process lock)
188       TXTLOCK,    --  Lock text segment into memory (text lock)
189       DATLOCK     --  Lock data segment into memory (data lock)
190      );
191
192   type Sproc_Attributes is record
193      Sproc_Resources : Resource_Vector_T      := NO_RESOURCES;
194      CPU             : CPU_Number             := ANY_CPU;
195      Resident        : Page_Locking           := NOLOCK;
196      NDPRI           : Non_Degrading_Priority := NDP_NONE;
197--  ??? why is that commented out, should it be removed ?
198--       Sproc_Slice     : Duration               := 0.0;
199--       Deadline_Period : Duration               := 0.0;
200--       Deadline_Alloc  : Duration               := 0.0;
201   end record;
202
203   Default_Sproc_Attributes : constant Sproc_Attributes :=
204      (NO_RESOURCES, ANY_CPU, NOLOCK, NDP_NONE);
205
206   function New_Sproc (Attr : Sproc_Attributes) return sproc_t;
207   function New_Sproc
208     (Sproc_Resources : Resource_Vector_T      := NO_RESOURCES;
209      CPU             : CPU_Number             := ANY_CPU;
210      Resident        : Page_Locking           := NOLOCK;
211      NDPRI           : Non_Degrading_Priority := NDP_NONE)
212      return            sproc_t;
213   --  Allocates a sproc_t control structure and creates the
214   --  corresponding sproc.
215
216   Invalid_CPU_Number : exception;
217   Permission_Error   : exception;
218   Sproc_Create_Error : exception;
219
220   -----------------------
221   -- Thread Attributes --
222   -----------------------
223
224   type Thread_Attributes (Bound_To_Sproc : Boolean) is record
225      Thread_Resources : Resource_Vector_T := NO_RESOURCES;
226
227      Thread_Timeslice : Duration          := 0.0;
228
229      case Bound_To_Sproc is
230         when False =>
231            null;
232         when True   =>
233            Sproc : sproc_t;
234      end case;
235   end record;
236
237   Default_Thread_Attributes : constant Thread_Attributes :=
238     (False, NO_RESOURCES, 0.0);
239
240   function Unbound_Thread_Attributes
241     (Thread_Resources : Resource_Vector_T := NO_RESOURCES;
242      Thread_Timeslice : Duration          := 0.0)
243      return             Thread_Attributes;
244
245   function Bound_Thread_Attributes
246     (Thread_Resources : Resource_Vector_T := NO_RESOURCES;
247      Thread_Timeslice : Duration          := 0.0;
248      Sproc            : sproc_t)
249      return             Thread_Attributes;
250
251   function Bound_Thread_Attributes
252     (Thread_Resources : Resource_Vector_T      := NO_RESOURCES;
253      Thread_Timeslice : Duration               := 0.0;
254      Sproc_Resources  : Resource_Vector_T      := NO_RESOURCES;
255      CPU              : CPU_Number             := ANY_CPU;
256      Resident         : Page_Locking           := NOLOCK;
257      NDPRI            : Non_Degrading_Priority := NDP_NONE)
258      return             Thread_Attributes;
259
260   type Task_Info_Type is access all Thread_Attributes;
261
262   function New_Unbound_Thread_Attributes
263     (Thread_Resources : Resource_Vector_T := NO_RESOURCES;
264      Thread_Timeslice : Duration          := 0.0)
265      return             Task_Info_Type;
266
267   function New_Bound_Thread_Attributes
268     (Thread_Resources : Resource_Vector_T := NO_RESOURCES;
269      Thread_Timeslice : Duration          := 0.0;
270      Sproc            : sproc_t)
271      return             Task_Info_Type;
272
273   function New_Bound_Thread_Attributes
274     (Thread_Resources : Resource_Vector_T      := NO_RESOURCES;
275      Thread_Timeslice : Duration               := 0.0;
276      Sproc_Resources  : Resource_Vector_T      := NO_RESOURCES;
277      CPU              : CPU_Number             := ANY_CPU;
278      Resident         : Page_Locking           := NOLOCK;
279      NDPRI            : Non_Degrading_Priority := NDP_NONE)
280      return             Task_Info_Type;
281
282   Unspecified_Task_Info : constant Task_Info_Type := null;
283
284end System.Task_Info;
285