root/src/common/db.h @ 2

Revision 1, 40.1 kB (checked in by jinshiro, 17 years ago)
Line 
1/*****************************************************************************\
2 *  Copyright (c) Athena Dev Teams - Licensed under GNU GPL                  *
3 *  For more information, see LICENCE in the main folder                     *
4 *                                                                           *
5 *  This file is separated in two sections:                                  *
6 *  (1) public typedefs, enums, unions, structures and defines               *
7 *  (2) public functions                                                     *
8 *                                                                           *
9 *  <B>Notes on the release system:</B>                                      *
10 *  Whenever an entry is removed from the database both the key and the      *
11 *  data are requested to be released.                                       *
12 *  At least one entry is removed when replacing an entry, removing an       *
13 *  entry, clearing the database or destroying the database.                 *
14 *  What is actually released is defined by the release function, the        *
15 *  functions of the database only ask for the key and/or data to be         *
16 *  released.                                                                *
17 *                                                                           *
18 *  TODO:                                                                    *
19 *  - create an enum for the data (with int, unsigned int and void *)        *
20 *  - create a custom database allocator                                     *
21 *  - see what functions need or should be added to the database interface   *
22 *                                                                           *
23 *  HISTORY:                                                                 *
24 *    2007/11/09 - Added an iterator to the database.
25 *    2.1 (Athena build #???#) - Portability fix                             *
26 *      - Fixed the portability of casting to union and added the functions  *
27 *        {@link DBMap#ensure(DBMap,DBKey,DBCreateData,...)} and             *
28 *        {@link DBMap#clear(DBMap,DBApply,...)}.                            *
29 *    2.0 (Athena build 4859) - Transition version                           *
30 *      - Almost everything recoded with a strategy similar to objects,      *
31 *        database structure is maintained.                                  *
32 *    1.0 (up to Athena build 4706)                                          *
33 *      - Previous database system.                                          *
34 *                                                                           *
35 * @version 2.1 (Athena build #???#) - Portability fix                       *
36 * @author (Athena build 4859) Flavio @ Amazon Project                       *
37 * @author (up to Athena build 4706) Athena Dev Teams                        *
38 * @encoding US-ASCII                                                        *
39 * @see common#db.c                                                          *
40\*****************************************************************************/
41#ifndef _DB_H_
42#define _DB_H_
43
44#include "../common/cbasetypes.h"
45#include <stdarg.h>
46
47/*****************************************************************************\
48 *  (1) Section with public typedefs, enums, unions, structures and defines. *
49 *  DB_MANUAL_CAST_TO_UNION - Define when the compiler doesn't allow casting *
50 *           to unions.                                                      *
51 *  DBRelease    - Enumeration of release options.                           *
52 *  DBType       - Enumeration of database types.                            *
53 *  DBOptions    - Bitfield enumeration of database options.                 *
54 *  DBKey        - Union of used key types.                                  *
55 *  DBApply      - Format of functions applyed to the databases.             *
56 *  DBMatcher    - Format of matchers used in DBMap::getall.                 *
57 *  DBComparator - Format of the comparators used by the databases.          *
58 *  DBHasher     - Format of the hashers used by the databases.              *
59 *  DBReleaser   - Format of the releasers used by the databases.            *
60 *  DBIterator   - Database iterator.                                        *
61 *  DBMap        - Database interface.                                       *
62\*****************************************************************************/
63
64/**
65 * Define this to enable the functions that cast to unions.
66 * Required when the compiler doesn't support casting to unions.
67 * NOTE: It is recommened that the conditional tests to determine if this
68 * should be defined be located in the configure script or a header file
69 * specific for compatibility and portability issues.
70 * @public
71 * @see #db_i2key(int)
72 * @see #db_ui2key(unsigned int)
73 * @see #db_str2key(unsigned char *)
74 */
75//#define DB_MANUAL_CAST_TO_UNION
76
77/**
78 * Bitfield with what should be released by the releaser function (if the
79 * function supports it).
80 * @public
81 * @see #DBReleaser
82 * @see #db_custom_release(DBRelease)
83 */
84typedef enum DBRelease {
85        DB_RELEASE_NOTHING = 0,
86        DB_RELEASE_KEY     = 1,
87        DB_RELEASE_DATA    = 2,
88        DB_RELEASE_BOTH    = 3
89} DBRelease;
90
91/**
92 * Supported types of database.
93 * See {@link #db_fix_options(DBType,DBOptions)} for restrictions of the
94 * types of databases.
95 * @param DB_INT Uses int's for keys
96 * @param DB_UINT Uses unsigned int's for keys
97 * @param DB_STRING Uses strings for keys.
98 * @param DB_ISTRING Uses case insensitive strings for keys.
99 * @public
100 * @see #DBOptions
101 * @see #DBKey
102 * @see #db_fix_options(DBType,DBOptions)
103 * @see #db_default_cmp(DBType)
104 * @see #db_default_hash(DBType)
105 * @see #db_default_release(DBType,DBOptions)
106 * @see #db_alloc(const char *,int,DBType,DBOptions,unsigned short)
107 */
108typedef enum DBType {
109        DB_INT,
110        DB_UINT,
111        DB_STRING,
112        DB_ISTRING
113} DBType;
114
115/**
116 * Bitfield of options that define the behaviour of the database.
117 * See {@link #db_fix_options(DBType,DBOptions)} for restrictions of the
118 * types of databases.
119 * @param DB_OPT_BASE Base options: does not duplicate keys, releases nothing
120 *          and does not allow NULL keys or NULL data.
121 * @param DB_OPT_DUP_KEY Duplicates the keys internally. If DB_OPT_RELEASE_KEY
122 *          is defined, the real key is freed as soon as the entry is added.
123 * @param DB_OPT_RELEASE_KEY Releases the key.
124 * @param DB_OPT_RELEASE_DATA Releases the data whenever an entry is removed
125 *          from the database.
126 *          WARNING: for funtions that return the data (like DBMap::remove),
127 *          a dangling pointer will be returned.
128 * @param DB_OPT_RELEASE_BOTH Releases both key and data.
129 * @param DB_OPT_ALLOW_NULL_KEY Allow NULL keys in the database.
130 * @param DB_OPT_ALLOW_NULL_DATA Allow NULL data in the database.
131 * @public
132 * @see #db_fix_options(DBType,DBOptions)
133 * @see #db_default_release(DBType,DBOptions)
134 * @see #db_alloc(const char *,int,DBType,DBOptions,unsigned short)
135 */
136typedef enum DBOptions {
137        DB_OPT_BASE            = 0,
138        DB_OPT_DUP_KEY         = 1,
139        DB_OPT_RELEASE_KEY     = 2,
140        DB_OPT_RELEASE_DATA    = 4,
141        DB_OPT_RELEASE_BOTH    = 6,
142        DB_OPT_ALLOW_NULL_KEY  = 8,
143        DB_OPT_ALLOW_NULL_DATA = 16,
144} DBOptions;
145
146/**
147 * Union of key types used by the database.
148 * @param i Type of key for DB_INT databases
149 * @param ui Type of key for DB_UINT databases
150 * @param str Type of key for DB_STRING and DB_ISTRING databases
151 * @public
152 * @see #DBType
153 * @see DBMap#get
154 * @see DBMap#put
155 * @see DBMap#remove
156 */
157typedef union DBKey {
158        int i;
159        unsigned int ui;
160        const char *str;
161} DBKey;
162
163/**
164 * Format of funtions that create the data for the key when the entry doesn't
165 * exist in the database yet.
166 * @param key Key of the database entry
167 * @param args Extra arguments of the funtion
168 * @return Data identified by the key to be put in the database
169 * @public
170 * @see DBMap#vensure
171 * @see DBMap#ensure
172 */
173typedef void* (*DBCreateData)(DBKey key, va_list args);
174
175/**
176 * Format of functions to be applyed to an unspecified quantity of entries of
177 * a database.
178 * Any function that applies this function to the database will return the sum
179 * of values returned by this function.
180 * @param key Key of the database entry
181 * @param data Data of the database entry
182 * @param args Extra arguments of the funtion
183 * @return Value to be added up by the funtion that is applying this
184 * @public
185 * @see DBMap#vforeach
186 * @see DBMap#foreach
187 * @see DBMap#vdestroy
188 * @see DBMap#destroy
189 */
190typedef int (*DBApply)(DBKey key, void* data, va_list args);
191
192/**
193 * Format of functions that match database entries.
194 * The purpose of the match depends on the function that is calling the matcher.
195 * Returns 0 if it is a match, another number otherwise.
196 * @param key Key of the database entry
197 * @param data Data of the database entry
198 * @param args Extra arguments of the function
199 * @return 0 if a match, another number otherwise
200 * @public
201 * @see DBMap#getall
202 */
203typedef int (*DBMatcher)(DBKey key, void* data, va_list args);
204
205/**
206 * Format of the comparators used internally by the database system.
207 * Compares key1 to key2.
208 * <code>maxlen</code> is the maximum number of character used in DB_STRING and
209 * DB_ISTRING databases. If 0, the maximum number of maxlen is used (64K).
210 * Returns 0 is equal, negative if lower and positive is higher.
211 * @param key1 Key being compared
212 * @param key2 Key we are comparing to
213 * @param maxlen Maximum number of characters used in DB_STRING and DB_ISTRING
214 *          databases.
215 * @return 0 if equal, negative if lower and positive if higher
216 * @public
217 * @see #db_default_cmp(DBType)
218 */
219typedef int (*DBComparator)(DBKey key1, DBKey key2, unsigned short maxlen);
220
221/**
222 * Format of the hashers used internally by the database system.
223 * Creates the hash of the key.
224 * <code>maxlen</code> is the maximum number of character used in DB_STRING and
225 * DB_ISTRING databases. If 0, the maximum number of maxlen is used (64K).
226 * @param key Key being hashed
227 * @param maxlen Maximum number of characters used in DB_STRING and DB_ISTRING
228 *          databases.
229 * @return Hash of the key
230 * @public
231 * @see #db_default_hash(DBType)
232 */
233typedef unsigned int (*DBHasher)(DBKey key, unsigned short maxlen);
234
235/**
236 * Format of the releaser used by the database system.
237 * Releases nothing, the key, the data or both.
238 * All standard releasers use aFree to release.
239 * @param key Key of the database entry
240 * @param data Data of the database entry
241 * @param which What is being requested to be released
242 * @public
243 * @see #DBRelease
244 * @see #db_default_releaser(DBType,DBOptions)
245 * @see #db_custom_release(DBRelease)
246 */
247typedef void (*DBReleaser)(DBKey key, void* data, DBRelease which);
248
249
250
251typedef struct DBIterator DBIterator;
252typedef struct DBMap DBMap;
253
254
255
256/**
257 * Database iterator.
258 * Supports forward iteration, backward iteration and removing entries from the database.
259 * The iterator is initially positioned before the first entry of the database.
260 * While the iterator exists the database is locked internally, so invoke
261 * {@link DBIterator#destroy} as soon as possible.
262 * @public
263 * @see #DBMap
264 */
265struct DBIterator
266{
267
268        /**
269         * Fetches the first entry in the database.
270         * Returns the data of the entry.
271         * Puts the key in out_key, if out_key is not NULL.
272         * @param self Iterator
273         * @param out_key Key of the entry
274         * @return Data of the entry
275         * @protected
276         */
277        void* (*first)(DBIterator* self, DBKey* out_key);
278
279        /**
280         * Fetches the last entry in the database.
281         * Returns the data of the entry.
282         * Puts the key in out_key, if out_key is not NULL.
283         * @param self Iterator
284         * @param out_key Key of the entry
285         * @return Data of the entry
286         * @protected
287         */
288        void* (*last)(DBIterator* self, DBKey* out_key);
289
290        /**
291         * Fetches the next entry in the database.
292         * Returns the data of the entry.
293         * Puts the key in out_key, if out_key is not NULL.
294         * @param self Iterator
295         * @param out_key Key of the entry
296         * @return Data of the entry
297         * @protected
298         */
299        void* (*next)(DBIterator* self, DBKey* out_key);
300
301        /**
302         * Fetches the previous entry in the database.
303         * Returns the data of the entry.
304         * Puts the key in out_key, if out_key is not NULL.
305         * @param self Iterator
306         * @param out_key Key of the entry
307         * @return Data of the entry
308         * @protected
309         */
310        void* (*prev)(DBIterator* self, DBKey* out_key);
311
312        /**
313         * Returns true if the fetched entry exists.
314         * The databases entries might have NULL data, so use this to to test if
315         * the iterator is done.
316         * @param self Iterator
317         * @return true is the entry exists
318         * @protected
319         */
320        bool (*exists)(DBIterator* self);
321
322        /**
323         * Removes the current entry from the database.
324         * NOTE: {@link DBIterator#exists} will return false until another entry
325         *       is fethed
326         * Returns the data of the entry.
327         * @param self Iterator
328         * @return The data of the entry or NULL if not found
329         * @protected
330         * @see DBMap#remove
331         */
332        void* (*remove)(DBIterator* self);
333
334        /**
335         * Destroys this iterator and unlocks the database.
336         * @param self Iterator
337         * @protected
338         */
339        void (*destroy)(DBIterator* self);
340
341};
342
343/**
344 * Public interface of a database. Only contains funtions.
345 * All the functions take the interface as the first argument.
346 * @public
347 * @see #db_alloc(const char*,int,DBType,DBOptions,unsigned short)
348 */
349struct DBMap {
350
351        /**
352         * Returns a new iterator for this database.
353         * The iterator keeps the database locked until it is destroyed.
354         * The database will keep functioning normally but will only free internal
355         * memory when unlocked, so destroy the iterator as soon as possible.
356         * @param self Database
357         * @return New iterator
358         * @protected
359         */
360        DBIterator* (*iterator)(DBMap* self);
361
362        /**
363         * Get the data of the entry identifid by the key.
364         * @param self Database
365         * @param key Key that identifies the entry
366         * @return Data of the entry or NULL if not found
367         * @protected
368         */
369        void* (*get)(DBMap* self, DBKey key);
370
371        /**
372         * Just calls {@link DBMap#vgetall}.
373         * Get the data of the entries matched by <code>match</code>.
374         * It puts a maximum of <code>max</code> entries into <code>buf</code>.
375         * If <code>buf</code> is NULL, it only counts the matches.
376         * Returns the number of entries that matched.
377         * NOTE: if the value returned is greater than <code>max</code>, only the
378         * first <code>max</code> entries found are put into the buffer.
379         * @param self Database
380         * @param buf Buffer to put the data of the matched entries
381         * @param max Maximum number of data entries to be put into buf
382         * @param match Function that matches the database entries
383         * @param ... Extra arguments for match
384         * @return The number of entries that matched
385         * @protected
386         * @see DBMap#vgetall(DBMap*,void **,unsigned int,DBMatcher,va_list)
387         */
388        unsigned int (*getall)(DBMap* self, void** buf, unsigned int max, DBMatcher match, ...);
389
390        /**
391         * Get the data of the entries matched by <code>match</code>.
392         * It puts a maximum of <code>max</code> entries into <code>buf</code>.
393         * If <code>buf</code> is NULL, it only counts the matches.
394         * Returns the number of entries that matched.
395         * NOTE: if the value returned is greater than <code>max</code>, only the
396         * first <code>max</code> entries found are put into the buffer.
397         * @param self Database
398         * @param buf Buffer to put the data of the matched entries
399         * @param max Maximum number of data entries to be put into buf
400         * @param match Function that matches the database entries
401         * @param ... Extra arguments for match
402         * @return The number of entries that matched
403         * @protected
404         * @see DBMap#getall(DBMap*,void **,unsigned int,DBMatcher,...)
405         */
406        unsigned int (*vgetall)(DBMap* self, void** buf, unsigned int max, DBMatcher match, va_list args);
407
408        /**
409         * Just calls {@link DBMap#vensure}.
410         * Get the data of the entry identified by the key.
411         * If the entry does not exist, an entry is added with the data returned by
412         * <code>create</code>.
413         * @param self Database
414         * @param key Key that identifies the entry
415         * @param create Function used to create the data if the entry doesn't exist
416         * @param ... Extra arguments for create
417         * @return Data of the entry
418         * @protected
419         * @see DBMap#vensure(DBMap*,DBKey,DBCreateData,va_list)
420         */
421        void* (*ensure)(DBMap* self, DBKey key, DBCreateData create, ...);
422
423        /**
424         * Get the data of the entry identified by the key.
425         * If the entry does not exist, an entry is added with the data returned by
426         * <code>create</code>.
427         * @param self Database
428         * @param key Key that identifies the entry
429         * @param create Function used to create the data if the entry doesn't exist
430         * @param args Extra arguments for create
431         * @return Data of the entry
432         * @protected
433         * @see DBMap#ensure(DBMap*,DBKey,DBCreateData,...)
434         */
435        void* (*vensure)(DBMap* self, DBKey key, DBCreateData create, va_list args);
436
437        /**
438         * Put the data identified by the key in the database.
439         * Returns the previous data if the entry exists or NULL.
440         * NOTE: Uses the new key, the old one is released.
441         * @param self Database
442         * @param key Key that identifies the data
443         * @param data Data to be put in the database
444         * @return The previous data if the entry exists or NULL
445         * @protected
446         */
447        void* (*put)(DBMap* self, DBKey key, void* data);
448
449        /**
450         * Remove an entry from the database.
451         * Returns the data of the entry.
452         * NOTE: The key (of the database) is released.
453         * @param self Database
454         * @param key Key that identifies the entry
455         * @return The data of the entry or NULL if not found
456         * @protected
457         */
458        void* (*remove)(DBMap* self, DBKey key);
459
460        /**
461         * Just calls {@link DBMap#vforeach}.
462         * Apply <code>func</code> to every entry in the database.
463         * Returns the sum of values returned by func.
464         * @param self Database
465         * @param func Function to be applyed
466         * @param ... Extra arguments for func
467         * @return Sum of the values returned by func
468         * @protected
469         * @see DBMap#vforeach(DBMap*,DBApply,va_list)
470         */
471        int (*foreach)(DBMap* self, DBApply func, ...);
472
473        /**
474         * Apply <code>func</code> to every entry in the database.
475         * Returns the sum of values returned by func.
476         * @param self Database
477         * @param func Function to be applyed
478         * @param args Extra arguments for func
479         * @return Sum of the values returned by func
480         * @protected
481         * @see DBMap#foreach(DBMap*,DBApply,...)
482         */
483        int (*vforeach)(DBMap* self, DBApply func, va_list args);
484
485        /**
486         * Just calls {@link DBMap#vclear}.
487         * Removes all entries from the database.
488         * Before deleting an entry, func is applyed to it.
489         * Releases the key and the data.
490         * Returns the sum of values returned by func, if it exists.
491         * @param self Database
492         * @param func Function to be applyed to every entry before deleting
493         * @param ... Extra arguments for func
494         * @return Sum of values returned by func
495         * @protected
496         * @see DBMap#vclear(DBMap*,DBApply,va_list)
497         */
498        int (*clear)(DBMap* self, DBApply func, ...);
499
500        /**
501         * Removes all entries from the database.
502         * Before deleting an entry, func is applyed to it.
503         * Releases the key and the data.
504         * Returns the sum of values returned by func, if it exists.
505         * @param self Database
506         * @param func Function to be applyed to every entry before deleting
507         * @param args Extra arguments for func
508         * @return Sum of values returned by func
509         * @protected
510         * @see DBMap#clear(DBMap*,DBApply,...)
511         */
512        int (*vclear)(DBMap* self, DBApply func, va_list args);
513
514        /**
515         * Just calls {@link DBMap#vdestroy}.
516         * Finalize the database, feeing all the memory it uses.
517         * Before deleting an entry, func is applyed to it.
518         * Releases the key and the data.
519         * Returns the sum of values returned by func, if it exists.
520         * NOTE: This locks the database globally. Any attempt to insert or remove
521         * a database entry will give an error and be aborted (except for clearing).
522         * @param self Database
523         * @param func Function to be applyed to every entry before deleting
524         * @param ... Extra arguments for func
525         * @return Sum of values returned by func
526         * @protected
527         * @see DBMap#vdestroy(DBMap*,DBApply,va_list)
528         */
529        int (*destroy)(DBMap* self, DBApply func, ...);
530
531        /**
532         * Finalize the database, feeing all the memory it uses.
533         * Before deleting an entry, func is applyed to it.
534         * Returns the sum of values returned by func, if it exists.
535         * NOTE: This locks the database globally. Any attempt to insert or remove
536         * a database entry will give an error and be aborted (except for clearing).
537         * @param self Database
538         * @param func Function to be applyed to every entry before deleting
539         * @param args Extra arguments for func
540         * @return Sum of values returned by func
541         * @protected
542         * @see DBMap#destroy(DBMap*,DBApply,...)
543         */
544        int (*vdestroy)(DBMap* self, DBApply func, va_list args);
545
546        /**
547         * Return the size of the database (number of items in the database).
548         * @param self Database
549         * @return Size of the database
550         * @protected
551         */
552        unsigned int (*size)(DBMap* self);
553
554        /**
555         * Return the type of the database.
556         * @param self Database
557         * @return Type of the database
558         * @protected
559         */
560        DBType (*type)(DBMap* self);
561
562        /**
563         * Return the options of the database.
564         * @param self Database
565         * @return Options of the database
566         * @protected
567         */
568        DBOptions (*options)(DBMap* self);
569
570};
571
572//For easy access to the common functions.
573#ifdef DB_MANUAL_CAST_TO_UNION
574#       define i2key   db_i2key
575#       define ui2key  db_ui2key
576#       define str2key db_str2key
577#else /* not DB_MANUAL_CAST_TO_UNION */
578#       define i2key(k)   ((DBKey)(int)(k))
579#       define ui2key(k)  ((DBKey)(unsigned int)(k))
580#       define str2key(k) ((DBKey)(const char *)(k))
581#endif /* not DB_MANUAL_CAST_TO_UNION */
582
583#define db_get(db,k)    ( (db)->get((db),(k)) )
584#define idb_get(db,k)   ( (db)->get((db),i2key(k)) )
585#define uidb_get(db,k)  ( (db)->get((db),ui2key(k)) )
586#define strdb_get(db,k) ( (db)->get((db),str2key(k)) )
587
588#define db_put(db,k,d)    ( (db)->put((db),(k),(d)) )
589#define idb_put(db,k,d)   ( (db)->put((db),i2key(k),(d)) )
590#define uidb_put(db,k,d)  ( (db)->put((db),ui2key(k),(d)) )
591#define strdb_put(db,k,d) ( (db)->put((db),str2key(k),(d)) )
592
593#define db_remove(db,k)    ( (db)->remove((db),(k)) )
594#define idb_remove(db,k)   ( (db)->remove((db),i2key(k)) )
595#define uidb_remove(db,k)  ( (db)->remove((db),ui2key(k)) )
596#define strdb_remove(db,k) ( (db)->remove((db),str2key(k)) )
597
598//These are discarding the possible vargs you could send to the function, so those
599//that require vargs must not use these defines.
600#define db_ensure(db,k,f)    ( (db)->ensure((db),(k),(f)) )
601#define idb_ensure(db,k,f)   ( (db)->ensure((db),i2key(k),(f)) )
602#define uidb_ensure(db,k,f)  ( (db)->ensure((db),ui2key(k),(f)) )
603#define strdb_ensure(db,k,f) ( (db)->ensure((db),str2key(k),(f)) )
604
605// Database creation and destruction macros
606#define idb_alloc(opt)            db_alloc(__FILE__,__LINE__,DB_INT,(opt),sizeof(int))
607#define uidb_alloc(opt)           db_alloc(__FILE__,__LINE__,DB_UINT,(opt),sizeof(unsigned int))
608#define strdb_alloc(opt,maxlen)   db_alloc(__FILE__,__LINE__,DB_STRING,(opt),(maxlen))
609#define stridb_alloc(opt,maxlen)  db_alloc(__FILE__,__LINE__,DB_ISTRING,(opt),(maxlen))
610#define db_destroy(db)            ( (db)->destroy((db),NULL) )
611// Other macros
612#define db_clear(db)        ( (db)->clear(db,NULL) )
613#define db_iterator(db)     ( (db)->iterator(db) )
614#define dbi_first(dbi)      ( (dbi)->first(dbi,NULL) )
615#define dbi_last(dbi)       ( (dbi)->last(dbi,NULL) )
616#define dbi_next(dbi)       ( (dbi)->next(dbi,NULL) )
617#define dbi_prev(dbi)       ( (dbi)->prev(dbi,NULL) )
618#define dbi_exists(dbi)     ( (dbi)->exists(dbi) )
619#define dbi_destroy(dbi)    ( (dbi)->destroy(dbi) )
620
621/*****************************************************************************\
622 *  (2) Section with public functions.                                       *
623 *  db_fix_options     - Fix the options for a type of database.             *
624 *  db_default_cmp     - Get the default comparator for a type of database.  *
625 *  db_default_hash    - Get the default hasher for a type of database.      *
626 *  db_default_release - Get the default releaser for a type of database     *
627 *           with the fixed options.                                         *
628 *  db_custom_release  - Get the releaser that behaves as specified.         *
629 *  db_alloc           - Allocate a new database.                            *
630 *  db_i2key           - Manual cast from 'int' to 'DBKey'.                  *
631 *  db_ui2key          - Manual cast from 'unsigned int' to 'DBKey'.         *
632 *  db_str2key         - Manual cast from 'unsigned char *' to 'DBKey'.      *
633 *  db_init            - Initialise the database system.                     *
634 *  db_final           - Finalise the database system.                       *
635\*****************************************************************************/
636
637/**
638 * Returns the fixed options according to the database type.
639 * Sets required options and unsets unsupported options.
640 * For numeric databases DB_OPT_DUP_KEY and DB_OPT_RELEASE_KEY are unset.
641 * @param type Type of the database
642 * @param options Original options of the database
643 * @return Fixed options of the database
644 * @private
645 * @see #DBType
646 * @see #DBOptions
647 * @see #db_default_release(DBType,DBOptions)
648 */
649DBOptions db_fix_options(DBType type, DBOptions options);
650
651/**
652 * Returns the default comparator for the type of database.
653 * @param type Type of database
654 * @return Comparator for the type of database or NULL if unknown database
655 * @public
656 * @see #DBType
657 * @see #DBComparator
658 */
659DBComparator db_default_cmp(DBType type);
660
661/**
662 * Returns the default hasher for the specified type of database.
663 * @param type Type of database
664 * @return Hasher of the type of database or NULL if unknown database
665 * @public
666 * @see #DBType
667 * @see #DBHasher
668 */
669DBHasher db_default_hash(DBType type);
670
671/**
672 * Returns the default releaser for the specified type of database with the
673 * specified options.
674 * NOTE: the options are fixed by {@link #db_fix_options(DBType,DBOptions)}
675 * before choosing the releaser
676 * @param type Type of database
677 * @param options Options of the database
678 * @return Default releaser for the type of database with the fixed options
679 * @public
680 * @see #DBType
681 * @see #DBOptions
682 * @see #DBReleaser
683 * @see #db_fix_options(DBType,DBOptions)
684 * @see #db_custom_release(DBRelease)
685 */
686DBReleaser db_default_release(DBType type, DBOptions options);
687
688/**
689 * Returns the releaser that behaves as <code>which</code> specifies.
690 * @param which Defines what the releaser releases
691 * @return Releaser for the specified release options
692 * @public
693 * @see #DBRelease
694 * @see #DBReleaser
695 * @see #db_default_release(DBType,DBOptions)
696 */
697DBReleaser db_custom_release(DBRelease which);
698
699/**
700 * Allocate a new database of the specified type.
701 * It uses the default comparator, hasher and releaser of the specified
702 * database type and fixed options.
703 * NOTE: the options are fixed by {@link #db_fix_options(DBType,DBOptions)}
704 * before creating the database.
705 * @param file File where the database is being allocated
706 * @param line Line of the file where the database is being allocated
707 * @param type Type of database
708 * @param options Options of the database
709 * @param maxlen Maximum length of the string to be used as key in string
710 *          databases
711 * @return The interface of the database
712 * @public
713 * @see #DBType
714 * @see #DBMap
715 * @see #db_default_cmp(DBType)
716 * @see #db_default_hash(DBType)
717 * @see #db_default_release(DBType,DBOptions)
718 * @see #db_fix_options(DBType,DBOptions)
719 */
720DBMap* db_alloc(const char *file, int line, DBType type, DBOptions options, unsigned short maxlen);
721
722#ifdef DB_MANUAL_CAST_TO_UNION
723/**
724 * Manual cast from 'int' to the union DBKey.
725 * Created for compilers that don't support casting to unions.
726 * @param key Key to be casted
727 * @return The key as a DBKey union
728 * @public
729 * @see #DB_MANUAL_CAST_TO_UNION
730 */
731DBKey db_i2key(int key);
732
733/**
734 * Manual cast from 'unsigned int' to the union DBKey.
735 * Created for compilers that don't support casting to unions.
736 * @param key Key to be casted
737 * @return The key as a DBKey union
738 * @public
739 * @see #DB_MANUAL_CAST_TO_UNION
740 */
741DBKey db_ui2key(unsigned int key);
742
743/**
744 * Manual cast from 'unsigned char *' to the union DBKey.
745 * Created for compilers that don't support casting to unions.
746 * @param key Key to be casted
747 * @return The key as a DBKey union
748 * @public
749 * @see #DB_MANUAL_CAST_TO_UNION
750 */
751DBKey db_str2key(const char *key);
752#endif /* DB_MANUAL_CAST_TO_UNION */
753
754/**
755 * Initialize the database system.
756 * @public
757 * @see #db_final(void)
758 */
759void db_init(void);
760
761/**
762 * Finalize the database system.
763 * Frees the memory used by the block reusage system.
764 * @public
765 * @see #db_init(void)
766 */
767void db_final(void);
768
769// Link DB System - From jAthena
770struct linkdb_node {
771        struct linkdb_node *next;
772        struct linkdb_node *prev;
773        void               *key;
774        void               *data;
775};
776
777void  linkdb_insert ( struct linkdb_node** head, void *key, void* data); // d•¡‚ðl—¶‚µ‚È‚¢
778void  linkdb_replace( struct linkdb_node** head, void *key, void* data); // d•¡‚ðl—¶‚·‚é
779void* linkdb_search ( struct linkdb_node** head, void *key);
780void* linkdb_erase  ( struct linkdb_node** head, void *key);
781void  linkdb_final  ( struct linkdb_node** head );
782
783
784
785/// Finds an entry in an array.
786/// ex: ARR_FIND(0, size, i, list[i] == target);
787///
788/// @param __start   Starting index (ex: 0)
789/// @param __end     End index (ex: size of the array)
790/// @param __var     Index variable
791/// @param __cmp     Expression that returns true when the target entry is found
792#define ARR_FIND(__start, __end, __var, __cmp) \
793        do{ \
794                for( (__var) = (__start); (__var) < (__end); ++(__var) ) \
795                        if( __cmp ) \
796                                break; \
797        }while(0)
798
799
800
801/// Moves an entry of the array.
802/// Use ARR_MOVERIGHT/ARR_MOVELEFT if __from and __to are direct numbers.
803/// ex: ARR_MOVE(i, 0, list, int);// move index i to index 0
804///
805///
806/// @param __from   Initial index of the entry
807/// @param __to     Target index of the entry
808/// @param __arr    Array
809/// @param __type   Type of entry
810#define ARR_MOVE(__from, __to, __arr, __type) \
811        do{ \
812                if( (__from) != (__to) ) \
813                { \
814                        __type __backup__; \
815                        memmove(&__backup__, (__arr)+(__from), sizeof(__type)); \
816                        if( (__from) < (__to) ) \
817                                memmove((__arr)+(__from), (__arr)+(__from)+1, ((__to)-(__from))*sizeof(__type)); \
818                        else if( (__from) > (__to) ) \
819                                memmove((__arr)+(__to)+1, (__arr)+(__to), ((__from)-(__to))*sizeof(__type)); \
820                        memmove((__arr)+(__to), &__backup__, sizeof(__type)); \
821                } \
822        }while(0)
823
824
825
826/// Moves an entry of the array to the right.
827/// ex: ARR_MOVERIGHT(1, 4, list, int);// move index 1 to index 4
828///
829/// @param __from   Initial index of the entry
830/// @param __to     Target index of the entry
831/// @param __arr    Array
832/// @param __type   Type of entry
833#define ARR_MOVERIGHT(__from, __to, __arr, __type) \
834        do{ \
835                __type __backup__; \
836                memmove(&__backup__, (__arr)+(__from), sizeof(__type)); \
837                memmove((__arr)+(__from), (__arr)+(__from)+1, ((__to)-(__from))*sizeof(__type)); \
838                memmove((__arr)+(__to), &__backup__, sizeof(__type)); \
839        }while(0)
840
841
842
843/// Moves an entry of the array to the left.
844/// ex: ARR_MOVELEFT(3, 0, list, int);// move index 3 to index 0
845///
846/// @param __from   Initial index of the entry
847/// @param __end    Target index of the entry
848/// @param __arr    Array
849/// @param __type   Type of entry
850#define ARR_MOVELEFT(__from, __to, __arr, __type) \
851        do{ \
852                __type __backup__; \
853                memmove(&__backup__, (__arr)+(__from), sizeof(__type)); \
854                memmove((__arr)+(__to)+1, (__arr)+(__to), ((__from)-(__to))*sizeof(__type)); \
855                memmove((__arr)+(__to), &__backup__, sizeof(__type)); \
856        }while(0)
857
858
859
860/////////////////////////////////////////////////////////////////////
861// Vector library based on defines. (dynamic array)
862// uses aMalloc, aRealloc, aFree
863
864
865
866/// Declares an anonymous vector struct.
867///
868/// @param __type Type of data
869#define VECTOR_DECL(__type) \
870        struct { \
871                size_t _max_; \
872                size_t _len_; \
873                __type* _data_; \
874        }
875
876
877
878/// Declares a named vector struct.
879///
880/// @param __name Structure name
881/// @param __type Type of data
882#define VECTOR_STRUCT_DECL(__name,__type) \
883        struct __name { \
884                size_t _max_; \
885                size_t _len_; \
886                __type* _data_; \
887        }
888
889
890
891/// Declares and initializes an anonymous vector variable.
892///
893/// @param __type Type of data
894/// @param __var Variable name
895#define VECTOR_VAR(__type,__var) \
896        VECTOR_DECL(__type) __var = {0,0,NULL}
897
898
899
900/// Declares and initializes a named vector variable.
901///
902/// @param __name Structure name
903/// @param __var Variable name
904#define VECTOR_STRUCT_VAR(__name,__var) \
905        struct __name __var = {0,0,NULL}
906
907
908
909/// Initializes a vector.
910///
911/// @param __vec Vector
912#define VECTOR_INIT(__vec) \
913        memset(&(__vec), 0, sizeof(__vec))
914
915
916
917/// Returns the internal array of values.
918///
919/// @param __vec Vector
920/// @return Array of values
921#define VECTOR_DATA(__vec) \
922        ( (__vec)._data_ )
923
924
925
926/// Returns the length of the vector.
927///
928/// @param __vec Vector
929/// @return Length
930#define VECTOR_LENGTH(__vec) \
931        ( (__vec)._len_ )
932
933
934
935/// Returns the capacity of the vector.
936///
937/// @param __vec Vector
938/// @return Capacity
939#define VECTOR_CAPACITY(__vec) \
940        ( (__vec)._max_ )
941
942
943
944/// Returns the value at the target index.
945/// Assumes the index exists.
946///
947/// @param __vec Vector
948/// @param __idx Index
949/// @return Value
950#define VECTOR_INDEX(__vec,__idx) \
951        ( VECTOR_DATA(__vec)[__idx] )
952
953
954
955/// Returns the first value of the vector.
956/// Assumes the array is not empty.
957///
958/// @param __vec Vector
959/// @return First value
960#define VECTOR_FIRST(__vec) \
961        ( VECTOR_INDEX(__vec,0) )
962
963
964
965/// Returns the last value of the vector.
966/// Assumes the array is not empty.
967///
968/// @param __vec Vector
969/// @return Last value
970#define VECTOR_LAST(__vec) \
971        ( VECTOR_INDEX(__vec,VECTOR_LENGTH(__vec)-1) )
972
973
974
975/// Resizes the vector.
976/// Excess values are discarded, new positions are zeroed.
977///
978/// @param __vec Vector
979/// @param __n Size
980#define VECTOR_RESIZE(__vec,__n) \
981        do{ \
982                if( (__n) > VECTOR_CAPACITY(__vec) ) \
983                { /* increase size */ \
984                        if( VECTOR_CAPACITY(__vec) == 0 ) VECTOR_DATA(__vec) = aMalloc((__n)*sizeof(VECTOR_FIRST(__vec))); /* allocate new */ \
985                        else VECTOR_DATA(__vec) = aRealloc(VECTOR_DATA(__vec),(__n)*sizeof(VECTOR_FIRST(__vec))); /* reallocate */ \
986                        memset(VECTOR_DATA(__vec)+VECTOR_LENGTH(__vec), 0, (VECTOR_CAPACITY(__vec)-VECTOR_LENGTH(__vec))*sizeof(VECTOR_FIRST(__vec))); /* clear new data */ \
987                        VECTOR_CAPACITY(__vec) = (__n); /* update capacity */ \
988                } \
989                else if( (__n) == 0 && VECTOR_CAPACITY(__vec) ) \
990                { /* clear vector */ \
991                        aFree(VECTOR_DATA(__vec)); VECTOR_DATA(__vec) = NULL; /* free data */ \
992                        VECTOR_CAPACITY(__vec) = 0; /* clear capacity */ \
993                        VECTOR_LENGTH(__vec) = 0; /* clear length */ \
994                } \
995                else if( (__n) < VECTOR_CAPACITY(__vec) ) \
996                { /* reduce size */ \
997                        VECTOR_DATA(__vec) = aRealloc(VECTOR_DATA(__vec),(__n)*sizeof(VECTOR_FIRST(__vec))); /* reallocate */ \
998                        VECTOR_CAPACITY(__vec) = (__n); /* update capacity */ \
999                        if( VECTOR_LENGTH(__vec) > (__n) ) VECTOR_LENGTH(__vec) = (__n); /* update length */ \
1000                } \
1001        }while(0)
1002
1003
1004
1005/// Ensures that the array has the target number of empty positions.
1006/// Increases the capacity in multiples of __step.
1007///
1008/// @param __vec Vector
1009/// @param __n Empty positions
1010/// @param __step Increase
1011#define VECTOR_ENSURE(__vec,__n,__step) \
1012        do{ \
1013                size_t _empty_ = VECTOR_CAPACITY(__vec)-VECTOR_LENGTH(__vec); \
1014                while( (__n) > _empty_ ) _empty_ += (__step); \
1015                if( _empty_ != VECTOR_CAPACITY(__vec)-VECTOR_LENGTH(__vec) ) VECTOR_RESIZE(__vec,_empty_+VECTOR_LENGTH(__vec)); \
1016        }while(0)
1017
1018
1019
1020/// Inserts a value in the target index. (using the '=' operator)
1021/// Assumes the index is valid and there is enough capacity.
1022///
1023/// @param __vec Vector
1024/// @param __idx Index
1025/// @param __val Value
1026#define VECTOR_INSERT(__vec,__idx,__val) \
1027        do{ \
1028                if( (__idx) < VECTOR_LENGTH(__vec) ) /* move data */ \
1029                        memmove(&VECTOR_INDEX(__vec,(__idx)+1),&VECTOR_INDEX(__vec,__idx),(VECTOR_LENGTH(__vec)-(__idx))*sizeof(VECTOR_FIRST(__vec))); \
1030                VECTOR_INDEX(__vec,__idx) = (__val); /* set value */ \
1031                ++VECTOR_LENGTH(__vec); /* increase length */ \
1032        }while(0)
1033
1034
1035
1036/// Inserts a value in the target index. (using memcpy)
1037/// Assumes the index is valid and there is enough capacity.
1038///
1039/// @param __vec Vector
1040/// @param __idx Index
1041/// @param __val Value
1042#define VECTOR_INSERTCOPY(__vec,__idx,__val) \
1043        VECTOR_INSERTARRAY(__vec,__idx,&(__val),1)
1044
1045
1046
1047/// Inserts the values of the array in the target index. (using memcpy)
1048/// Assumes the index is valid and there is enough capacity.
1049///
1050/// @param __vec Vector
1051/// @param __idx Index
1052/// @param __pval Array of values
1053/// @param __n Number of values
1054#define VECTOR_INSERTARRAY(__vec,__idx,__pval,__n) \
1055        do{ \
1056                if( (__idx) < VECTOR_LENGTH(__vec) ) /* move data */ \
1057                        memmove(&VECTOR_INDEX(__vec,(__idx)+(__n)),&VECTOR_INDEX(__vec,__idx),(VECTOR_LENGTH(__vec)-(__idx))*sizeof(VECTOR_FIRST(__vec))); \
1058                memcpy(&VECTOR_INDEX(__vec,__idx), (__pval), (__n)*sizeof(VECTOR_FIRST(__vec))); /* set values */ \
1059                VECTOR_LENGTH(__vec) += (__n); /* increase length */ \
1060        }while(0)
1061
1062
1063
1064/// Inserts a value in the end of the vector. (using the '=' operator)
1065/// Assumes there is enough capacity.
1066///
1067/// @param __vec Vector
1068/// @param __val Value
1069#define VECTOR_PUSH(__vec,__val) \
1070        do{ \
1071                VECTOR_INDEX(__vec,VECTOR_LENGTH(__vec)) = (__val); /* set value */ \
1072                ++VECTOR_LENGTH(__vec); /* increase length */ \
1073        }while(0)
1074
1075
1076
1077/// Inserts a value in the end of the vector. (using memcpy)
1078/// Assumes there is enough capacity.
1079///
1080/// @param __vec Vector
1081/// @param __val Value
1082#define VECTOR_PUSHCOPY(__vec,__val) \
1083        VECTOR_PUSHARRAY(__vec,&(__val),1)
1084
1085
1086
1087/// Inserts the values of the array in the end of the vector. (using memcpy)
1088/// Assumes there is enough capacity.
1089///
1090/// @param __vec Vector
1091/// @param __pval Array of values
1092/// @param __n Number of values
1093#define VECTOR_PUSHARRAY(__vec,__pval,__n) \
1094        do{ \
1095                memcpy(&VECTOR_INDEX(__vec,VECTOR_LENGTH(__vec)), (__pval), (__n)*sizeof(VECTOR_FIRST(__vec))); /* set values */ \
1096                VECTOR_LENGTH(__vec) += (__n); /* increase length */ \
1097        }while(0)
1098
1099
1100
1101/// Removes and returns the last value of the vector.
1102/// Assumes the array is not empty.
1103///
1104/// @param __vec Vector
1105/// @return Removed value
1106#define VECTOR_POP(__vec) \
1107        ( VECTOR_INDEX(__vec,--VECTOR_LENGTH(__vec)) )
1108
1109
1110
1111/// Removes the last N values of the vector and returns the value of the last pop.
1112/// Assumes there are enough values.
1113///
1114/// @param __vec Vector
1115/// @param __n Number of pops
1116/// @return Last removed value
1117#define VECTOR_POPN(__vec,__n) \
1118        ( VECTOR_INDEX(__vec,(VECTOR_LENGTH(__vec)-=(__n))) )
1119
1120
1121
1122/// Removes the target index from the vector.
1123/// Assumes the index is valid and there are enough values.
1124///
1125/// @param __vec Vector
1126/// @param __idx Index
1127#define VECTOR_ERASE(__vec,__idx) \
1128        VECTOR_ERASEN(__vec,__idx,1)
1129
1130
1131
1132/// Removes N values from the target index of the vector.
1133/// Assumes the index is valid and there are enough values.
1134///
1135/// @param __vec Vector
1136/// @param __idx Index
1137/// @param __n Number of values
1138#define VECTOR_ERASEN(__vec,__idx,__n) \
1139        do{ \
1140                if( (__idx) < VECTOR_LENGTH(__vec)-(__n) ) /* move data */ \
1141                        memmove(&VECTOR_INDEX(__vec,__idx),&VECTOR_INDEX(__vec,(__idx)+(__n)),(VECTOR_LENGTH(__vec)-((__idx)+(__n)))*sizeof(VECTOR_FIRST(__vec))); \
1142                VECTOR_LENGTH(__vec) -= (__n); /* decrease length */ \
1143        }while(0)
1144
1145
1146
1147/// Clears the vector, freeing allocated data.
1148///
1149/// @param __vec Vector
1150#define VECTOR_CLEAR(__vec) \
1151        do{ \
1152                if( VECTOR_CAPACITY(__vec) ) \
1153                { \
1154                        aFree(VECTOR_DATA(__vec)); VECTOR_DATA(__vec) = NULL; /* clear allocated array */ \
1155                        VECTOR_CAPACITY(__vec) = 0; /* clear capacity */ \
1156                        VECTOR_LENGTH(__vec) = 0; /* clear length */ \
1157                } \
1158        }while(0)
1159
1160
1161
1162#endif /* _DB_H_ */
Note: See TracBrowser for help on using the browser.