1 ------------------------------------------------------------------------------
3 -- GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS --
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 --
10 -- Copyright (C) 1992-2001, Free Software Foundation, Inc. --
12 -- GNARL is free software; you can redistribute it and/or modify it under --
13 -- terms of the GNU General Public License as published by the Free Soft- --
14 -- ware Foundation; either version 2, or (at your option) any later ver- --
15 -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
16 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
17 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
18 -- for more details. You should have received a copy of the GNU General --
19 -- Public License distributed with GNARL; see file COPYING. If not, write --
20 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
21 -- MA 02111-1307, USA. --
23 -- As a special exception, if other files instantiate generics from this --
24 -- unit, or you link this unit with other files to produce an executable, --
25 -- this unit does not by itself cause the resulting executable to be --
26 -- covered by the GNU General Public License. This exception does not --
27 -- however invalidate any other reasons why the executable file might be --
28 -- covered by the GNU Public License. --
30 -- GNARL was developed by the GNARL team at Florida State University. --
31 -- Extensive contributions were provided by Ada Core Technologies Inc. --
33 ------------------------------------------------------------------------------
35 -- This package provides necessary definitions to handle simple (i.e without
36 -- entries) protected objects.
38 -- All the routines that handle protected objects with entries have been moved
39 -- to two children: Entries and Operations. Note that Entries only contains
40 -- the type declaration and the OO primitives. This is needed to avoid
41 -- circular dependency.
43 -- This package is part of the high level tasking interface used by the
44 -- compiler to expand Ada 95 tasking constructs into simpler run time calls
45 -- (aka GNARLI, GNU Ada Run-time Library Interface)
47 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
48 -- Any changes to this interface may require corresponding compiler changes
49 -- in exp_ch9.adb and possibly exp_ch7.adb
51 package System.Tasking.Protected_Objects is
52 pragma Elaborate_Body;
54 ---------------------------------
55 -- Compiler Interface (GNARLI) --
56 ---------------------------------
58 -- The compiler will expand in the GNAT tree the following construct:
63 -- open : boolean := false;
66 -- protected body PO is
68 -- ...variable declarations...
76 -- protected type poT is
79 -- open : boolean := false;
81 -- type poTV is limited record
82 -- open : boolean := false;
83 -- _object : aliased protection;
85 -- procedure poPT__pN (_object : in out poTV);
86 -- procedure poPT__pP (_object : in out poTV);
88 -- procedure _init_proc (_init : in out poTV) is
90 -- _init.open := false;
91 -- _init_proc (_init._object);
92 -- initialize_protection (_init._object'unchecked_access,
93 -- unspecified_priority);
98 -- _init_proc (poTV!(po));
100 -- procedure poPT__pN (_object : in out poTV) is
101 -- poR : protection renames _object._object;
102 -- openP : boolean renames _object.open;
103 -- ...variable declarations...
109 -- procedure poPT__pP (_object : in out poTV) is
110 -- procedure _clean is
112 -- unlock (_object._object'unchecked_access);
116 -- lock (_object._object'unchecked_access);
118 -- poPT__pN (_object);
125 Null_Protected_Entry : constant := Null_Entry;
127 Max_Protected_Entry : constant := Max_Entry;
129 type Protected_Entry_Index is new Entry_Index
130 range Null_Protected_Entry .. Max_Protected_Entry;
132 type Barrier_Function_Pointer is access
135 E : Protected_Entry_Index)
137 -- Pointer to a function which evaluates the barrier of a protected
138 -- entry body. O is a pointer to the compiler-generated record
139 -- representing the protected object, and E is the index of the
140 -- entry serviced by the body.
142 type Entry_Action_Pointer is access
146 E : Protected_Entry_Index);
147 -- Pointer to a procedure which executes the sequence of statements
148 -- of a protected entry body. O is a pointer to the compiler-generated
149 -- record representing the protected object, P is a pointer to the
150 -- record of entry parameters, and E is the index of the
151 -- entry serviced by the body.
153 type Entry_Body is record
154 Barrier : Barrier_Function_Pointer;
155 Action : Entry_Action_Pointer;
157 -- The compiler-generated code passes objects of this type to the GNARL
158 -- to allow it to access the executable code of an entry body.
160 type Entry_Body_Access is access all Entry_Body;
162 type Protection is limited private;
163 -- This type contains the GNARL state of a protected object. The
164 -- application-defined portion of the state (i.e. private objects)
165 -- is maintained by the compiler-generated code.
166 -- Note that there are now 2 Protection types. One for the simple
167 -- case (no entries) and one for the general case that needs the whole
168 -- Finalization mechanism.
169 -- This split helps in the case of restricted run time where we want to
170 -- minimize the size of the code.
172 type Protection_Access is access all Protection;
174 Null_PO : constant Protection_Access := null;
176 procedure Initialize_Protection
177 (Object : Protection_Access;
178 Ceiling_Priority : Integer);
179 -- Initialize the Object parameter so that it can be used by the runtime
180 -- to keep track of the runtime state of a protected object.
182 procedure Lock (Object : Protection_Access);
183 -- Lock a protected object for write access. Upon return, the caller
184 -- owns the lock to this object, and no other call to Lock or
185 -- Lock_Read_Only with the same argument will return until the
186 -- corresponding call to Unlock has been made by the caller.
188 procedure Lock_Read_Only (Object : Protection_Access);
189 -- Lock a protected object for read access. Upon return, the caller
190 -- owns the lock for read access, and no other calls to Lock with the
191 -- same argument will return until the corresponding call to Unlock
192 -- has been made by the caller. Other calls to Lock_Read_Only may (but
193 -- need not) return before the call to Unlock, and the corresponding
194 -- callers will also own the lock for read access.
196 -- Note: we are not currently using this interface, it is provided
197 -- for possible future use. At the current time, everyone uses Lock
198 -- for both read and write locks.
200 procedure Unlock (Object : Protection_Access);
201 -- Relinquish ownership of the lock for the object represented by
202 -- the Object parameter. If this ownership was for write access, or
203 -- if it was for read access where there are no other read access
204 -- locks outstanding, one (or more, in the case of Lock_Read_Only)
205 -- of the tasks waiting on this lock (if any) will be given the
206 -- lock and allowed to return from the Lock or Lock_Read_Only call.
209 type Protection is record
210 L : aliased Task_Primitives.Lock;
211 Ceiling : System.Any_Priority;
213 pragma Volatile (Protection);
214 for Protection'Alignment use Standard'Maximum_Alignment;
215 -- Needed so that we can uncheck convert a Protection_Access to a
216 -- Protection_Entries_Access.
218 procedure Finalize_Protection (Object : in out Protection);
219 -- Clean up a Protection object; in particular, finalize the associated
220 -- Lock object. The compiler generates automatically calls to this
223 end System.Tasking.Protected_Objects;