File: /home/oboss/Users/gec/sources/Basic_Services/Containers/protected_map_type.ads
1 --% Compilation Unit: Protected_Map_Type
2 --
3 --% Category: Generic Package Declaration
4 --
5 --% Release: $Name: $
6 --
7 --% Version: $Revision: 2.0 $
8 --
9 --% Author: $Author: gec $
10 --
11 --% Revision Log:
12 -- $Log: protected_map_type.ads,v $
13 -- Revision 2.0 2003/04/04 08:49:57 gec
14 -- Initial release of source files serving as baseline for OBOSS-III project.
15 --
16 -- Revision 1.1.1.1 2003/04/04 08:13:00 gec
17 -- Imported using TkCVS
18 --
19 --
20 --
21 --% Project: OBOSS
22 --
23 --% Copyright (C) 2003 by Terma A/S
24 -- Proprietary and intellectual rights of Terma A/S, Denmark,
25 -- are involved in the subject-matter of this material and
26 -- all manufacturing, reproduction, use, disclosure, and
27 -- sales rights pertaining to such subject-matter are
28 -- expressly reserved. This material is submitted for a
29 -- specific purpose as agreed, and the recipient by
30 -- accepting this material agrees that this material will
31 -- not be used, copied, or reproduced in whole or in part
32 -- nor its contents revealed in any manner or to any person,
33 -- except to meet the purpose for which it was submitted and
34 -- subject to the terms of the agreement.
35 --
36 --% Target Dependencies:
37 -- None
38 --% Compiler Dependencies:
39 -- None
40
41 --~-----------------------------------------------------------------------------
42
43 with Task_Priority_Control;
44 with Map_Type;
45 generic
46
47 --% Generic Parameter Constraints:
48 --> Protected_Task_Priority - Shall be equal to the ceiling of priorities
49 --+ of all tasks using services from the event scheduler
50
51 -- Maximum number of entries to be contained in map.
52 Max_Number_Of_Entries : in Positive;
53
54 -- Type of keys used to look-up in map. Referred to as domain of map.
55 type Key_Type is (<>);
56
57 -- Type of elements associated to keys in map. Referred to as range of map.
58 -- Access type included for efficiency reasons.
59 type Element_Type is private;
60 type Element_Type_Reference is access Element_Type;
61
62 -- Priority of critical region making operations on map data structures
63 --+ atomic
64 Protected_Map_Priority
65 : in Task_Priority_Control.Passive_Task_Priority;
66
67 package Protected_Map_Type is
68
69 --% Library Package:
70 -- Implementation of general map type associating data elements to keys.
71 -- All operations are atomic, i.e. protected against concurrent
72 --+ execution.
73 --% Active Tasks:
74 --> None
75 --% Passive Tasks:
76 --> None
77
78 -- A look-up operation failed as given key does not have an entry in map.
79 Not_In_Map : exception;
80
81 -- An insertion operation failed as given key already has an entry in map.
82 Already_In_Map : exception;
83
84 -- An insertion operation failed as number of map entries has reached
85 --+ Max_Number_Of_Entries.
86 Map_Size_Exceeded : exception;
87
88 -- Indicates that no elements are left in an iteration over the map domain
89 --+ or range
90 Iterator_Exhausted : exception;
91
92 -- Iterator over the map range, i.e. the data elements contained in the
93 --+ map.
94 type Map_Range is private;
95
96 -- Iterator over the map domain, i.e. the keys for which an entry exists in
97 --+ the map.
98 type Map_Domain is private;
99
100 procedure Initialize;
101
102 --------------------------------------
103 -- Normal map operations
104
105 --% Subprogram:
106 -- Remove any entries from the map, resulting in an empty map.
107 --% Parameter Constraints:
108 --> None
109 --% Exceptions Raised:
110 --> None
111 procedure Make_Map_Empty;
112
113 --% Subprogram:
114 -- Add an entry to the map, associating Elem to Key.
115 --% Parameter Constraints:
116 --> None
117 --% Exceptions Raised:
118 --> Already_In_Map - Map already contains an entry for Key
119 procedure Insert
120 (Key : in Key_Type;
121 Elem : in Element_Type);
122
123 --% Subprogram:
124 -- Remove the entry associating data to Key from the map.
125 --% Parameter Constraints:
126 --> None
127 --% Exceptions Raised:
128 --> Not_In_Map - Map does not contain an entry for Key
129 procedure Remove
130 (Key : in Key_Type);
131
132 --% Subprogram:
133 -- Replace the data element associated to Key with Elem.
134 --% Parameter Constraints:
135 --> None
136 --% Exceptions Raised:
137 --> Not_In_Map - Map does not contain an entry for Key
138 procedure Replace
139 (Key : in Key_Type;
140 Elem : in Element_Type);
141
142 --% Subprogram:
143 -- Look-up Key in map returning the data element associated to Key.
144 --% Parameter Constraints:
145 --> None
146 --% Exceptions Raised:
147 --> Not_In_Map - Map does not contain an entry for Key
148 function Apply
149 (Key : in Key_Type)
150 return Element_Type;
151
152 --% Subprogram:
153 -- Look-up Key in map returning accessor the data element associated to
154 --+ Key.
155 --% Parameter Constraints:
156 --> None
157 --% Exceptions Raised:
158 --> Not_In_Map - Map does not contain an entry for Key
159 function Apply
160 (Key : in Key_Type)
161 return Element_Type_Reference;
162
163 --% Subprogram:
164 -- Predicate indicating whether map contains an entry for Key.
165 --% Parameter Constraints:
166 --> None
167 --% Exceptions Raised:
168 --> None
169 function Is_In
170 (Key : in Key_Type)
171 return Boolean;
172
173
174 --------------------------------------------------------------
175 -- Operations on domain iterators
176
177 --% Subprogram:
178 -- Constructor for iterators over the map domain (i.e. the set of keys).
179 --% Parameter Constraints:
180 --> None
181 --% Exceptions Raised:
182 --> None
183 function Get_Domain
184 return Map_Domain;
185
186 --% Subprogram:
187 -- Predicate indicating whether the entire map domain has been covered by
188 --+ Iterator.
189 --% Parameter Constraints:
190 --> None
191 --% Exceptions Raised:
192 --> None
193 function Domain_Is_Covered
194 (Iterator : in Map_Domain)
195 return Boolean;
196
197 --% Subprogram:
198 -- Successor operator for domain iterators. Key is next key in iteration.
199 --+
200 --% Parameter Constraints:
201 --> None
202 --% Exceptions Raised:
203 --> Iterator_Exhausted - Entire domain has been covered by Iterator.
204 procedure Get_Next_Key_In_Domain
205 (Iterator : in out Map_Domain;
206 Key : out Key_Type);
207
208
209 --------------------------------------------------------------
210 -- Operations on range iterators
211
212 --% Subprogram:
213 -- Constructor for iterators over the map range (i.e. the set of data
214 --+ elements).
215 --% Parameter Constraints:
216 --> None
217 --% Exceptions Raised:
218 --> None
219 function Get_Range
220 return Map_Range;
221
222 --% Subprogram:
223 -- Predicate indicating whether the entire map range has been covered by
224 --+ Iterator.
225 --% Parameter Constraints:
226 --> None
227 --% Exceptions Raised:
228 --> None
229 function Range_Is_Covered
230 (Iterator : in Map_Range)
231 return Boolean;
232
233 --% Subprogram:
234 -- Successor operator for range iterators. Element is next data element
235 --+ in iteration.
236 --% Parameter Constraints:
237 --> None
238 --% Exceptions Raised:
239 --> Iterator_Exhausted - Entire range has been covered by Iterator.
240 procedure Get_Next_Element_In_Range
241 (Iterator : in out Map_Range;
242 Element : out Element_Type);
243
244 --% Subprogram:
245 -- Successor operator for range iterators. Element is next data element
246 --+ in iteration.
247 --% Parameter Constraints:
248 --> None
249 --% Exceptions Raised:
250 --> Iterator_Exhausted - Entire range has been covered by Iterator.
251 procedure Get_Next_Element_In_Range
252 (Iterator : in out Map_Range;
253 Element_Reference : out Element_Type_Reference);
254
255 private
256
257 -- An unprotected map type
258 package The_Map is new Map_Type
259 (Max_Number_Of_Entries => Max_Number_Of_Entries,
260 Key_Type => Key_Type,
261 Element_Type => Element_Type,
262 Element_Type_Reference => Element_Type_Reference);
263
264 type Map_Range is new The_Map.Map_Range;
265 type Map_Domain is new The_Map.Map_Domain;
266
267 end Protected_Map_Type;
268
269 --~-----------------------------------------------------------------------------
270