diff options
author | Christian Grothoff <christian@grothoff.org> | 2010-11-05 21:54:44 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2010-11-05 21:54:44 +0000 |
commit | bdc3b54372a92874c2ecb58069eac5bdfe6fcddc (patch) | |
tree | 575c606a8f81c1f0baabad43bf34789023513ee7 /src/include/gnunet_datastore_plugin.h | |
parent | f0963cfb7a694f9a7c7ff28471660242529f00a8 (diff) | |
download | gnunet-bdc3b54372a92874c2ecb58069eac5bdfe6fcddc.tar.gz gnunet-bdc3b54372a92874c2ecb58069eac5bdfe6fcddc.zip |
moving plugin headers
Diffstat (limited to 'src/include/gnunet_datastore_plugin.h')
-rw-r--r-- | src/include/gnunet_datastore_plugin.h | 342 |
1 files changed, 342 insertions, 0 deletions
diff --git a/src/include/gnunet_datastore_plugin.h b/src/include/gnunet_datastore_plugin.h new file mode 100644 index 000000000..832d53a68 --- /dev/null +++ b/src/include/gnunet_datastore_plugin.h | |||
@@ -0,0 +1,342 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | (C) 2009 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 2, or (at your | ||
8 | option) any later version. | ||
9 | |||
10 | GNUnet is distributed in the hope that it will be useful, but | ||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file datastore/gnunet_datastore_plugin.h | ||
23 | * @brief API for the database backend plugins. | ||
24 | * @author Christian Grothoff | ||
25 | */ | ||
26 | #ifndef PLUGIN_DATASTORE_H | ||
27 | #define PLUGIN_DATASTORE_H | ||
28 | |||
29 | #include "gnunet_block_lib.h" | ||
30 | #include "gnunet_configuration_lib.h" | ||
31 | #include "gnunet_datastore_service.h" | ||
32 | #include "gnunet_statistics_service.h" | ||
33 | #include "gnunet_scheduler_lib.h" | ||
34 | |||
35 | |||
36 | /** | ||
37 | * How many bytes of overhead will we assume per entry | ||
38 | * in any DB (for reservations)? | ||
39 | */ | ||
40 | #define GNUNET_DATASTORE_ENTRY_OVERHEAD 256 | ||
41 | |||
42 | |||
43 | /** | ||
44 | * Function invoked to notify service of disk utilization | ||
45 | * changes. | ||
46 | * | ||
47 | * @param cls closure | ||
48 | * @param delta change in disk utilization, | ||
49 | * 0 for "reset to empty" | ||
50 | */ | ||
51 | typedef void (*DiskUtilizationChange)(void *cls, | ||
52 | int delta); | ||
53 | |||
54 | |||
55 | /** | ||
56 | * The datastore service will pass a pointer to a struct | ||
57 | * of this type as the first and only argument to the | ||
58 | * entry point of each datastore plugin. | ||
59 | */ | ||
60 | struct GNUNET_DATASTORE_PluginEnvironment | ||
61 | { | ||
62 | /** | ||
63 | * Configuration to use. | ||
64 | */ | ||
65 | const struct GNUNET_CONFIGURATION_Handle *cfg; | ||
66 | |||
67 | /** | ||
68 | * Function to call on disk utilization change. | ||
69 | */ | ||
70 | DiskUtilizationChange duc; | ||
71 | |||
72 | /** | ||
73 | * Closure. | ||
74 | */ | ||
75 | void *cls; | ||
76 | |||
77 | }; | ||
78 | |||
79 | |||
80 | /** | ||
81 | * Function invoked on behalf of a "PluginIterator" | ||
82 | * asking the database plugin to call the iterator | ||
83 | * with the next item. | ||
84 | * | ||
85 | * @param next_cls whatever argument was given | ||
86 | * to the PluginIterator as "next_cls". | ||
87 | * @param end_it set to GNUNET_YES if we | ||
88 | * should terminate the iteration early | ||
89 | * (iterator should be still called once more | ||
90 | * to signal the end of the iteration). | ||
91 | */ | ||
92 | typedef void (*PluginNextRequest)(void *next_cls, | ||
93 | int end_it); | ||
94 | |||
95 | |||
96 | /** | ||
97 | * An iterator over a set of items stored in the datastore. | ||
98 | * | ||
99 | * @param cls closure | ||
100 | * @param next_cls closure to pass to the "next" function. | ||
101 | * @param key key for the content | ||
102 | * @param size number of bytes in data | ||
103 | * @param data content stored | ||
104 | * @param type type of the content | ||
105 | * @param priority priority of the content | ||
106 | * @param anonymity anonymity-level for the content | ||
107 | * @param expiration expiration time for the content | ||
108 | * @param uid unique identifier for the datum; | ||
109 | * maybe 0 if no unique identifier is available | ||
110 | * | ||
111 | * @return GNUNET_SYSERR to abort the iteration, GNUNET_OK to continue | ||
112 | * (continue on call to "next", of course), | ||
113 | * GNUNET_NO to delete the item and continue (if supported) | ||
114 | */ | ||
115 | typedef int (*PluginIterator) (void *cls, | ||
116 | void *next_cls, | ||
117 | const GNUNET_HashCode * key, | ||
118 | uint32_t size, | ||
119 | const void *data, | ||
120 | enum GNUNET_BLOCK_Type type, | ||
121 | uint32_t priority, | ||
122 | uint32_t anonymity, | ||
123 | struct GNUNET_TIME_Absolute | ||
124 | expiration, | ||
125 | uint64_t uid); | ||
126 | |||
127 | /** | ||
128 | * Get an estimate of how much space the database is | ||
129 | * currently using. | ||
130 | * | ||
131 | * @param cls closure | ||
132 | * @return number of bytes used on disk | ||
133 | */ | ||
134 | typedef unsigned long long (*PluginGetSize) (void *cls); | ||
135 | |||
136 | |||
137 | /** | ||
138 | * Store an item in the datastore. If the item is already present, | ||
139 | * the priorities are summed up and the higher expiration time and | ||
140 | * lower anonymity level is used. | ||
141 | * | ||
142 | * @param cls closure | ||
143 | * @param key key for the item | ||
144 | * @param size number of bytes in data | ||
145 | * @param data content stored | ||
146 | * @param type type of the content | ||
147 | * @param priority priority of the content | ||
148 | * @param anonymity anonymity-level for the content | ||
149 | * @param expiration expiration time for the content | ||
150 | * @param msg set to an error message (on failure) | ||
151 | * @return GNUNET_OK on success, GNUNET_NO if the content | ||
152 | * was already present (and may have been updated); | ||
153 | * GNUNET_SYSERR on failure | ||
154 | */ | ||
155 | typedef int (*PluginPut) (void *cls, | ||
156 | const GNUNET_HashCode * key, | ||
157 | uint32_t size, | ||
158 | const void *data, | ||
159 | enum GNUNET_BLOCK_Type type, | ||
160 | uint32_t priority, | ||
161 | uint32_t anonymity, | ||
162 | struct GNUNET_TIME_Absolute expiration, | ||
163 | char **msg); | ||
164 | |||
165 | |||
166 | /** | ||
167 | * Iterate over the results for a particular key | ||
168 | * in the datastore. | ||
169 | * | ||
170 | * @param cls closure | ||
171 | * @param key maybe NULL (to match all entries) | ||
172 | * @param vhash hash of the value, maybe NULL (to | ||
173 | * match all values that have the right key). | ||
174 | * Note that for DBlocks there is no difference | ||
175 | * betwen key and vhash, but for other blocks | ||
176 | * there may be! | ||
177 | * @param type entries of which type are relevant? | ||
178 | * Use 0 for any type. | ||
179 | * @param iter function to call on each matching value; however, | ||
180 | * after the first call to "iter", the plugin must wait | ||
181 | * until "NextRequest" was called before giving the iterator | ||
182 | * the next item; finally, the "iter" should be called once | ||
183 | * once with a NULL value at the end ("next_cls" should be NULL | ||
184 | * for that last call) | ||
185 | * @param iter_cls closure for iter | ||
186 | */ | ||
187 | typedef void (*PluginGet) (void *cls, | ||
188 | const GNUNET_HashCode * key, | ||
189 | const GNUNET_HashCode * vhash, | ||
190 | enum GNUNET_BLOCK_Type type, | ||
191 | PluginIterator iter, void *iter_cls); | ||
192 | |||
193 | |||
194 | /** | ||
195 | * Update the priority for a particular key in the datastore. If | ||
196 | * the expiration time in value is different than the time found in | ||
197 | * the datastore, the higher value should be kept. For the | ||
198 | * anonymity level, the lower value is to be used. The specified | ||
199 | * priority should be added to the existing priority, ignoring the | ||
200 | * priority in value. | ||
201 | * | ||
202 | * Note that it is possible for multiple values to match this put. | ||
203 | * In that case, all of the respective values are updated. | ||
204 | * | ||
205 | * @param cls closure | ||
206 | * @param uid unique identifier of the datum | ||
207 | * @param delta by how much should the priority | ||
208 | * change? If priority + delta < 0 the | ||
209 | * priority should be set to 0 (never go | ||
210 | * negative). | ||
211 | * @param expire new expiration time should be the | ||
212 | * MAX of any existing expiration time and | ||
213 | * this value | ||
214 | * @param msg set to an error message (on error) | ||
215 | * @return GNUNET_OK on success | ||
216 | */ | ||
217 | typedef int (*PluginUpdate) (void *cls, | ||
218 | uint64_t uid, | ||
219 | int delta, struct GNUNET_TIME_Absolute expire, | ||
220 | char **msg); | ||
221 | |||
222 | |||
223 | /** | ||
224 | * Select a subset of the items in the datastore and call | ||
225 | * the given iterator for each of them. | ||
226 | * | ||
227 | * @param cls closure | ||
228 | * @param type entries of which type should be considered? | ||
229 | * Use 0 for any type. | ||
230 | * @param iter function to call on each matching value; however, | ||
231 | * after the first call to "iter", the plugin must wait | ||
232 | * until "NextRequest" was called before giving the iterator | ||
233 | * the next item; finally, the "iter" should be called once | ||
234 | * once with a NULL value at the end ("next_cls" should be NULL | ||
235 | * for that last call) | ||
236 | * @param iter_cls closure for iter | ||
237 | */ | ||
238 | typedef void (*PluginSelector) (void *cls, | ||
239 | enum GNUNET_BLOCK_Type type, | ||
240 | PluginIterator iter, | ||
241 | void *iter_cls); | ||
242 | |||
243 | /** | ||
244 | * Drop database. | ||
245 | * | ||
246 | * @param cls closure | ||
247 | */ | ||
248 | typedef void (*PluginDrop) (void *cls); | ||
249 | |||
250 | |||
251 | |||
252 | /** | ||
253 | * Each plugin is required to return a pointer to a struct of this | ||
254 | * type as the return value from its entry point. | ||
255 | */ | ||
256 | struct GNUNET_DATASTORE_PluginFunctions | ||
257 | { | ||
258 | |||
259 | /** | ||
260 | * Closure to use for all of the following callbacks | ||
261 | * (except "next_request"). | ||
262 | */ | ||
263 | void *cls; | ||
264 | |||
265 | /** | ||
266 | * Get the current on-disk size of the SQ store. Estimates are | ||
267 | * fine, if that's the only thing available. | ||
268 | */ | ||
269 | PluginGetSize get_size; | ||
270 | |||
271 | /** | ||
272 | * Function to store an item in the datastore. | ||
273 | */ | ||
274 | PluginPut put; | ||
275 | |||
276 | /** | ||
277 | * Function called by iterators whenever they want the next value; | ||
278 | * note that unlike all of the other callbacks, this one does get a | ||
279 | * the "next_cls" closure which is usually different from the "cls" | ||
280 | * member of this struct! | ||
281 | */ | ||
282 | PluginNextRequest next_request; | ||
283 | |||
284 | /** | ||
285 | * Function to iterate over the results for a particular key | ||
286 | * in the datastore. | ||
287 | */ | ||
288 | PluginGet get; | ||
289 | |||
290 | /** | ||
291 | * Update the priority for a particular key in the datastore. If | ||
292 | * the expiration time in value is different than the time found in | ||
293 | * the datastore, the higher value should be kept. For the | ||
294 | * anonymity level, the lower value is to be used. The specified | ||
295 | * priority should be added to the existing priority, ignoring the | ||
296 | * priority in value. | ||
297 | */ | ||
298 | PluginUpdate update; | ||
299 | |||
300 | /** | ||
301 | * Iterate over the items in the datastore in ascending | ||
302 | * order of priority. | ||
303 | */ | ||
304 | PluginSelector iter_low_priority; | ||
305 | |||
306 | /** | ||
307 | * Iterate over content with anonymity zero. | ||
308 | */ | ||
309 | PluginSelector iter_zero_anonymity; | ||
310 | |||
311 | /** | ||
312 | * Iterate over the items in the datastore in ascending order of | ||
313 | * expiration time. | ||
314 | */ | ||
315 | PluginSelector iter_ascending_expiration; | ||
316 | |||
317 | /** | ||
318 | * Iterate over the items in the datastore in migration | ||
319 | * order. Call the given function on the next item only | ||
320 | * (and then signal 'end' with a second call). This is | ||
321 | * a significant difference from all the other iterators! | ||
322 | */ | ||
323 | PluginSelector iter_migration_order; | ||
324 | |||
325 | /** | ||
326 | * Iterate over all the items in the datastore | ||
327 | * as fast as possible in a single transaction | ||
328 | * (can lock datastore while this happens, focus | ||
329 | * is on doing it fast). | ||
330 | */ | ||
331 | PluginSelector iter_all_now; | ||
332 | |||
333 | /** | ||
334 | * Delete the database. The next operation is | ||
335 | * guaranteed to be unloading of the module. | ||
336 | */ | ||
337 | PluginDrop drop; | ||
338 | |||
339 | }; | ||
340 | |||
341 | |||
342 | #endif | ||