File : s-taprob-raven.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS --
4 -- --
5 -- S Y S T E M . T A S K I N G . P R O T E C T E D _ O B J E C T S --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1992-2016, 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. 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. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNARL was developed by the GNARL team at Florida State University. --
28 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -- This is the Ravenscar/HIE version of this package
33
34 -- This package provides necessary definitions to handle simple (i.e without
35 -- entries) protected objects.
36
37 -- All the routines that handle protected objects with entries have been moved
38 -- to two children: Entries and Operations. Note that Entries only contains
39 -- the type declaration and the OO primitives. This is needed to avoid
40 -- circular dependency.
41
42 -- This package is part of the high level tasking interface used by the
43 -- compiler to expand Ada 95 tasking constructs into simpler run time calls
44 -- (aka GNARLI, GNU Ada Run-time Library Interface)
45
46 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
47 -- Any changes to this interface may require corresponding compiler changes
48 -- in exp_ch9.adb and possibly exp_ch7.adb
49
50 with System.Multiprocessors.Fair_Locks;
51
52 package System.Tasking.Protected_Objects is
53 pragma Elaborate_Body;
54
55 ---------------------------------
56 -- Compiler Interface (GNARLI) --
57 ---------------------------------
58
59 -- The compiler will expand in the GNAT tree the following construct:
60
61 -- protected PO is
62 -- procedure P;
63 -- private
64 -- open : boolean := false;
65 -- end PO;
66
67 -- protected body PO is
68 -- procedure P is
69 -- ...variable declarations...
70 -- begin
71 -- ...B...
72 -- end P;
73 -- end PO;
74
75 -- as follows:
76
77 -- protected type poT is
78 -- procedure p;
79 -- private
80 -- open : boolean := false;
81 -- end poT;
82 -- type poTV is limited record
83 -- open : boolean := false;
84 -- _object : aliased protection;
85 -- end record;
86 -- procedure poPT__pN (_object : in out poTV);
87 -- procedure poPT__pP (_object : in out poTV);
88 -- freeze poTV [
89 -- procedure poTVIP (_init : in out poTV) is
90 -- begin
91 -- _init.open := false;
92 -- obj-init-proc (_init._object);
93 -- initialize_protection (_init._object'unchecked_access,
94 -- unspecified_priority);
95 -- return;
96 -- end poTVIP;
97 -- ]
98 -- po : poT;
99 -- poTVIP (poTV!(po));
100
101 -- procedure poPT__pN (_object : in out poTV) is
102 -- poR : protection renames _object._object;
103 -- openP : boolean renames _object.open;
104 -- ...variable declarations...
105 -- begin
106 -- ...B...
107 -- return;
108 -- end poPT__pN;
109
110 -- procedure poPT__pP (_object : in out poTV) is
111 -- procedure _clean is
112 -- begin
113 -- unlock (_object._object'unchecked_access);
114 -- return;
115 -- end _clean;
116 -- begin
117 -- lock (_object._object'unchecked_access);
118 -- B2b : begin
119 -- poPT__pN (_object);
120 -- at end
121 -- _clean;
122 -- end B2b;
123 -- return;
124 -- end poPT__pP;
125
126 Null_Protected_Entry : constant := Null_Entry;
127
128 Max_Protected_Entry : constant := Max_Entry;
129
130 type Protected_Entry_Index is new Entry_Index
131 range Null_Protected_Entry .. Max_Protected_Entry;
132
133 type Barrier_Function_Pointer is access
134 function
135 (O : System.Address;
136 E : Protected_Entry_Index)
137 return Boolean;
138 -- Pointer to a function which evaluates the barrier of a protected
139 -- entry body. O is a pointer to the compiler-generated record
140 -- representing the protected object, and E is the index of the
141 -- entry serviced by the body.
142
143 type Entry_Action_Pointer is access
144 procedure
145 (O : System.Address;
146 P : System.Address;
147 E : Protected_Entry_Index);
148 -- Pointer to a procedure which executes the sequence of statements
149 -- of a protected entry body. O is a pointer to the compiler-generated
150 -- record representing the protected object, P is a pointer to the
151 -- record of entry parameters, and E is the index of the
152 -- entry serviced by the body.
153
154 type Entry_Body is record
155 Barrier : Barrier_Function_Pointer;
156 Action : Entry_Action_Pointer;
157 end record;
158 -- The compiler-generated code passes objects of this type to the GNARL
159 -- to allow it to access the executable code of an entry body.
160
161 type Entry_Body_Access is access all Entry_Body;
162
163 type Protection is limited private;
164 -- This type contains the GNARL state of a protected object. The
165 -- application-defined portion of the state (i.e. private objects)
166 -- is maintained by the compiler-generated code.
167 --
168 -- Note that there are now 2 Protection types. One for the simple
169 -- case (no entries) and one for the general case that needs the whole
170 -- Finalization mechanism.
171 --
172 -- This split helps in the case of restricted run time where we want to
173 -- minimize the size of the code.
174
175 type Protection_Access is access all Protection;
176
177 Null_PO : constant Protection_Access := null;
178
179 procedure Initialize_Protection
180 (Object : Protection_Access;
181 Ceiling_Priority : Integer);
182 -- Initialize the Object parameter so that it can be used by the runtime
183 -- to keep track of the runtime state of a protected object.
184
185 procedure Lock (Object : Protection_Access);
186 -- Lock a protected object for write access. Upon return, the caller owns
187 -- the lock to this object, and no other call to Lock with the same
188 -- argument will return until the corresponding call to Unlock has been
189 -- made by the caller.
190
191 procedure Lock_Read_Only (Object : Protection_Access) renames Lock;
192 -- Lock a protected object for read access. Upon return, the caller
193 -- owns the lock for read access, and no other calls to Lock with the
194 -- same argument will return until the corresponding call to Unlock
195 -- has been made by the caller. Other calls to Lock_Read_Only may (but
196 -- need not) return before the call to Unlock, and the corresponding
197 -- callers will also own the lock for read access.
198
199 procedure Unlock (Object : Protection_Access);
200 -- Relinquish ownership of the lock for the object represented by the
201 -- Object parameter. One of the tasks waiting on this lock (if any) will
202 -- be given the lock and allowed to return from the Lock call.
203
204 private
205 type Protection is record
206 Ceiling : System.Any_Priority;
207 -- Ceiling priority associated to the protected object
208
209 Caller_Priority : System.Any_Priority;
210 -- Task's active priority when the protected operation was called. This
211 -- priority is restored when the task relinquish the protected object.
212
213 Owner : Task_Id;
214 -- This field contains the protected object's owner. Null_Task
215 -- indicates that the protected object is not currently being used.
216 -- This information is used for detecting the type of potentially
217 -- blocking operations described in the ARM 9.5.1, par. 15 (external
218 -- calls on a protected subprogram with the same target object as that
219 -- of the protected action).
220
221 Lock : Multiprocessors.Fair_Locks.Fair_Lock;
222 -- SMP lock
223 end record;
224 pragma Suppress_Initialization (Protection);
225
226 end System.Tasking.Protected_Objects;