File: /home/oboss/Users/gec/sources/Basic_Services/Containers/hashed_protected_map_type.ads
1 --% Compilation Unit: Hashed_Protected_Map_Type
2 --
3 --% Category: Generic Package Declaration
4 --
5 --% Release: $Name: $
6 --
7 --% Version: $Revision: 2.1 $
8 --
9 --% Author: $Author: jhl $
10 --
11 --% Revision Log:
12 -- $Log: hashed_protected_map_type.ads,v $
13 -- Revision 2.1 2003/10/09 11:05:14 jhl
14 -- Added Service 13 And 19
15 --
16 -- Revision 1.1.2.2 2003/10/03 10:11:49 jhl
17 -- Large Data Transfer post review updates
18 --
19 -- Revision 1.1.2.1 2003/10/01 11:54:18 jhl
20 -- Initial version of service 13 Event Action, and 19 Large Data Transfer.
21 --
22 -- Revision 2.0 2003/04/04 10:08:58 gec
23 -- Initial release serving as baseline for OBOSS-III project.
24 --
25 -- Revision 1.1.1.1 2003/04/04 07:19:20 gec
26 -- Imported using TkCVS
27 --
28 --
29 --
30 --% Project: OBOSS
31 --
32 --% Copyright (C) 2003 by Terma A/S
33 -- Proprietary and intellectual rights of Terma A/S, Denmark,
34 -- are involved in the subject-matter of this material and
35 -- all manufacturing, reproduction, use, disclosure, and
36 -- sales rights pertaining to such subject-matter are
37 -- expressly reserved. This material is submitted for a
38 -- specific purpose as agreed, and the recipient by
39 -- accepting this material agrees that this material will
40 -- not be used, copied, or reproduced in whole or in part
41 -- nor its contents revealed in any manner or to any person,
42 -- except to meet the purpose for which it was submitted and
43 -- subject to the terms of the agreement.
44 --
45 --% Target Dependencies:
46 -- None
47 --% Compiler Dependencies:
48 -- None
49
50 --~-----------------------------------------------------------------------------
51
52 with Task_Priority_Control;
53 with Protected_Map_Type;
54 generic
55
56 --% Generic Parameter Constraints:
57 --> Protected_Task_Priority - Shall be equal to the ceiling of priorities
58 --+ of all tasks using the hashed protected map
59 --> The hash function MUST be unique:
60 --> A one-to-one mapping of keys to hashed keys.
61 --> Otherwise the structure of the package breaks down.
62
63 -- Maximum number of entries to be contained in map.
64 Max_Number_Of_Entries : in Positive;
65
66 -- Key type to be used in map
67 type Key_Type is private;
68
69 -- Internal discrete key type in map
70 type Hashed_Key_Type is (<>);
71
72 -- Hash function mapping key type to unique internal key type.
73 -- Constraints:
74 -- The hash function must be re-entrant.
75 with function Unique_Hash
76 (Key : in Key_Type)
77 return Hashed_Key_Type;
78
79 -- Type of elements associated to keys in map.
80 -- Access type included for efficiency reasons.
81 type Element_Type is private;
82 type Element_Type_Reference is access Element_Type;
83
84 -- Priority of critical region making operations on map data structures
85 --+ atomic
86 Protected_Map_Priority : in Task_Priority_Control.Passive_Task_Priority;
87
88 package Hashed_Protected_Map_Type is
89
90 --% Library Package:
91 -- Implementation of general protected map type associating data elements
92 --+ to keys.
93 -- A unique (re-entrant) hash function associates the key to a hashed
94 --+ key.
95 -- Provides normal map operations as well as operations based on access
96 --+ type (avoids copying of large objects).
97 -- Access to map elements are based on locks being read-only or
98 --+ read-write.
99 -- Multiple read-only locks or one read-write lock can be obtained, but
100 --+ not both.
101 -- Deletion of locked elements is possible. The element will be deleted
102 --+ later when all locks have been released.
103 --% Active Tasks:
104 --> None
105 --% Passive Tasks:
106 --> None
107
108 -- A look-up operation failed as given key does not have an entry in map.
109 Not_In_Map : exception;
110
111 -- An insertion operation failed as given key already has an entry in map.
112 Already_In_Map : exception;
113
114 -- An insertion operation failed as number of map entries has reached
115 --+ Max_Number_Of_Entries.
116 Map_Size_Exceeded : exception;
117
118 -- Indicates that no elements are left in an iteration over the map domain
119 --+ or range
120 Iterator_Exhausted : exception;
121
122 -- Iterator over the map range, i.e. the data elements contained in the map.
123 --+
124 type Map_Range is private;
125
126 -- Iterator over the map domain, i.e. the hashed keys for which an entry
127 --+ exists in the map.
128 type Map_Domain is private;
129
130 --------------------------------------
131 -- Normal map operations
132
133 --% Subprogram:
134 -- Remove any entries from the map, resulting in an empty map.
135 --% Parameter Constraints:
136 --> None
137 --% Exceptions Raised:
138 --> None
139 procedure Make_Map_Empty;
140
141 --% Subprogram:
142 -- Add an entry to the map, associating Elem to Key.
143 --% Parameter Constraints:
144 --> None
145 --% Exceptions Raised:
146 --> Already_In_Map - Map already contains an entry for Key
147 --> Map_Size_Exeeded - Map size is exeeded. Element not inserted.
148 procedure Insert
149 (Key : in Key_Type;
150 Elem : in Element_Type);
151
152 --% Subprogram:
153 -- Remove the entry associating data to Key from the map.
154 --% Parameter Constraints:
155 --> None
156 --% Exceptions Raised:
157 --> Not_In_Map - Map does not contain an entry for Key
158 procedure Remove
159 (Key : in Key_Type);
160
161 --% Subprogram:
162 -- Replace the data element associated to Key with Elem.
163 --% Parameter Constraints:
164 --> None
165 --% Exceptions Raised:
166 --> Not_In_Map - Map does not contain an entry for Key
167 procedure Replace
168 (Key : in Key_Type;
169 Elem : in Element_Type);
170
171 --% Subprogram:
172 -- Look-up Key in map returning the data element associated to Key.
173 --% Parameter Constraints:
174 --> None
175 --% Exceptions Raised:
176 --> Not_In_Map - Map does not contain an entry for Key
177 function Apply
178 (Key : in Key_Type)
179 return Element_Type;
180
181 --% Subprogram:
182 -- Look-up Key in map returning accessor to the data element associated to
183 --+ Key.
184 --% Parameter Constraints:
185 --> None
186 --% Exceptions Raised:
187 --> Not_In_Map - Map does not contain an entry for Key
188 function Apply
189 (Key : in Key_Type)
190 return Element_Type_Reference;
191
192 --% Subprogram:
193 -- Predicate indicating whether map contains an entry for Key.
194 --% Parameter Constraints:
195 --> None
196 --% Exceptions Raised:
197 --> None
198 function Is_In
199 (Key : in Key_Type)
200 return Boolean;
201
202 --------------------------------------------------------------
203 -- Operations on domain iterators
204
205 --% Subprogram:
206 -- Constructor for iterators over the map domain (i.e. the set of keys).
207 --% Parameter Constraints:
208 --> None
209 --% Exceptions Raised:
210 --> None
211 function Get_Domain
212 return Map_Domain;
213
214 --% Subprogram:
215 -- Predicate indicating whether the entire map domain has been covered by
216 --+ Iterator.
217 --% Parameter Constraints:
218 --> None
219 --% Exceptions Raised:
220 --> None
221 function Domain_Is_Covered
222 (Iterator : in Map_Domain)
223 return Boolean;
224
225 --% Subprogram:
226 -- Successor operator for domain iterators. Hashed Key is next hashed key
227 --+ in iteration.
228 --% Parameter Constraints:
229 --> None
230 --% Exceptions Raised:
231 --> Iterator_Exhausted - Entire domain has been covered by Iterator.
232 procedure Get_Next_Hashed_Key_In_Domain
233 (Iterator : in out Map_Domain;
234 Hashed_Key : out Hashed_Key_Type);
235
236 --------------------------------------------------------------
237 -- Operations on range iterators
238
239 --% Subprogram:
240 -- Constructor for iterators over the map range (i.e. the set of data
241 --+ elements).
242 --% Parameter Constraints:
243 --> None
244 --% Exceptions Raised:
245 --> None
246 function Get_Range
247 return Map_Range;
248
249 --% Subprogram:
250 -- Predicate indicating whether the entire map range has been covered by
251 --+ Iterator.
252 --% Parameter Constraints:
253 --> None
254 --% Exceptions Raised:
255 --> None
256 function Range_Is_Covered
257 (Iterator : in Map_Range)
258 return Boolean;
259
260 --% Subprogram:
261 -- Successor operator for range iterators. Element is next data element
262 --+ in iteration.
263 --% Parameter Constraints:
264 --> None
265 --% Exceptions Raised:
266 --> Iterator_Exhausted - Entire range has been covered by Iterator.
267 procedure Get_Next_Element_In_Range
268 (Iterator : in out Map_Range;
269 Element : out Element_Type);
270
271 --% Subprogram:
272 -- Successor operator for range iterators. Element is next data element
273 --+ in iteration.
274 -- A lock of the class indicated by Lock is placed on element.
275 --% Parameter Constraints:
276 --> None
277 --% Exceptions Raised:
278 --> Iterator_Exhausted - Entire range has been covered by Iterator.
279 --> Lock_Violated - Read-Write lock exists on element.
280 procedure Get_Next_Element_In_Range
281 (Iterator : in out Map_Range;
282 Element_Reference : out Element_Type_Reference);
283
284 private
285
286 --% Package:
287 -- Map_Type is used as the basis for the Hashed_Map_Type.
288 -- It is instantiated here to allow the use of Map_Range and Map_Domain
289
290 -- Protected simple map type
291 package Simple_Map is new Protected_Map_Type
292 (Max_Number_Of_Entries => Max_Number_Of_Entries,
293 Key_Type => Hashed_Key_Type,
294 Element_Type => Element_Type,
295 Element_Type_Reference => Element_Type_Reference,
296 Protected_Map_Priority => Protected_Map_Priority);
297
298 type Map_Range is new Simple_Map.Map_Range;
299 type Map_Domain is new Simple_Map.Map_Domain;
300
301 end Hashed_Protected_Map_Type;
302
303 --~-----------------------------------------------------------------------------
304