1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28#ifdef KHRN_GENERIC_MAP_RELOCATABLE
29 #include "middleware/khronos/common/khrn_mem.h"
30#endif
31
32typedef struct {
33 KHRN_GENERIC_MAP_KEY_T key;
34 KHRN_GENERIC_MAP_VALUE_T value;
35} KHRN_GENERIC_MAP(ENTRY_T);
36
37typedef struct {
38 uint32_t entries;
39 uint32_t deletes;
40
41#ifdef KHRN_GENERIC_MAP_RELOCATABLE
42 MEM_HANDLE_T storage;
43#else
44 KHRN_GENERIC_MAP(ENTRY_T) *storage;
45#endif
46 uint32_t capacity;
47} KHRN_GENERIC_MAP(T);
48
49/*
50 bool khrn_generic_map(init)(KHRN_GENERIC_MAP(T) *map, uint32_t capacity)
51
52 Initialises the map
53
54 Preconditions:
55
56 map is a valid pointer to an uninitialised KHRN_GENERIC_MAP(T) structure
57 capacity >= 8
58
59 Postconditions:
60
61 Either:
62 - true is returned and the structure that map points to is valid, or
63 - false is returned and map is still uninitialised
64*/
65
66extern bool khrn_generic_map(init)(KHRN_GENERIC_MAP(T) *map, uint32_t capacity);
67
68/*
69 void khrn_generic_map(term)(KHRN_GENERIC_MAP(T) *map)
70
71 Terminates the map
72
73 Preconditions:
74
75 map is a valid pointer to a map whose values are of type X:
76 - where type X does not imply any external references, or
77 - KHRN_GENERIC_MAP_RELEASE_VALUE releases all of these references, or
78 - the map is empty
79
80 Postconditions:
81
82 The structure map points to is uninitialised
83*/
84
85extern void khrn_generic_map(term)(KHRN_GENERIC_MAP(T) *map);
86
87/*
88 bool khrn_generic_map(insert)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key, KHRN_GENERIC_MAP_VALUE_T value)
89
90 Inserts value into map with key key. If another value is already in the map
91 with this key, the function will not fail; the new value replaces the old
92
93 Preconditions:
94
95 map is a valid pointer to a map whose values are of type X
96 value is a valid value of type X
97
98 Postconditions:
99
100 If the function succeeds:
101 - true is returned
102 - key key is now associated with value
103 otherwise:
104 - false is returned
105 - map is unchanged
106*/
107
108extern bool khrn_generic_map(insert)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key, KHRN_GENERIC_MAP_VALUE_T value);
109
110/*
111 bool khrn_generic_map(delete)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key)
112
113 If present, deletes the element identified by key from the map and returns
114 true. If not present, returns false
115
116 Preconditions:
117
118 map is a valid pointer to a map
119
120 Postconditions:
121
122 key is not present in map
123*/
124
125extern bool khrn_generic_map(delete)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key);
126
127extern uint32_t khrn_generic_map(get_count)(KHRN_GENERIC_MAP(T) *map);
128
129/*
130 KHRN_GENERIC_MAP_VALUE_T khrn_generic_map(lookup)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key)
131
132 Returns the element of the map identified by key, or
133 KHRN_GENERIC_MAP_VALUE_NONE if no such element exists in the map
134
135 Preconditions:
136
137 map is a valid pointer to a map whose elements are of type X
138
139 Postconditions:
140
141 result is either KHRN_GENERIC_MAP_VALUE_NONE or a valid value of type X
142*/
143
144extern KHRN_GENERIC_MAP_VALUE_T khrn_generic_map(lookup)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key);
145
146/*
147 KHRN_GENERIC_MAP_VALUE_T khrn_generic_map(lookup_locked)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key, void *storage)
148
149 Returns the element of the map identified by key, or
150 KHRN_GENERIC_MAP_VALUE_NONE if no such element exists in the map
151
152 Preconditions:
153
154 map is a valid pointer to a map whose elements are of type X
155 storage is the locked pointer to map->storage
156
157 Postconditions:
158
159 result is either KHRN_GENERIC_MAP_VALUE_NONE or a valid value of type X
160*/
161
162#ifdef KHRN_GENERIC_MAP_RELOCATABLE
163 extern KHRN_GENERIC_MAP_VALUE_T khrn_generic_map(lookup_locked)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key, void *storage);
164#endif
165
166/*
167 void khrn_generic_map(iterate)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP(CALLBACK_T) func, void *data)
168
169 Runs the given callback function once for every (key, value) pair in the map.
170 Also passes data to the function
171
172 Implementation notes:
173
174 The iterator function is allowed to delete the element it is given, but not
175 modify the structure of map in any other way (eg by adding new elements)
176
177 Preconditions:
178
179 map is a valid pointer to a map of element type X
180 data, map satisfy P
181 func satisfies:
182 [
183 void func(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key, KHRN_GENERIC_MAP_VALUE_T value, void *data)
184
185 Preconditions:
186
187 data, map satisfy P
188 value is of type X
189 key is a key in map
190 map[key] == value
191
192 Postconditions:
193
194 func does not alter map, except possibly by deleting the element it is given
195 value is of type Y
196 ]
197
198 Postconditions:
199
200 func has been called on every (key, value) pair in the map
201 map is a valid pointer to a map of element type Y
202*/
203
204typedef void (*KHRN_GENERIC_MAP(CALLBACK_T))(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP_KEY_T key, KHRN_GENERIC_MAP_VALUE_T value, void *);
205extern void khrn_generic_map(iterate)(KHRN_GENERIC_MAP(T) *map, KHRN_GENERIC_MAP(CALLBACK_T) func, void *);
206