map.h

   1 /*
   2         Map
   3         ---
   4
   5         Thread safe map/set, using a Tree.
   6         Useful for managing big amounts of objects with add, get and del access from multiple                   threads.
   7 */
   8
   9 #ifndef _DRAGONSTD_MAP_H_ // include guard
  10 #define _DRAGONSTD_MAP_H_
  11
  12 #include <stdbool.h>       // for bool
  13 #include <pthread.h>       // for pthread_rwlock_t
  14 #include "tree.h"          // for Tree
  15
  16 typedef struct {
  17         /* private */
  18         Tree tre;             // search tree to manage data
  19         pthread_rwlock_t tlk; // lock to protect tree
  20         bool cnl;             // cancel state
  21         pthread_rwlock_t clk; // lock to protect cancel state
  22 } Map;
  23
  24 void map_ini(Map *map);
  25 /*
  26         Initializes the map.
  27
  28         The map should be uninitialized before passed to this function.
  29         This function should be called before any other function is called on the tree.
  30 */
  31
  32 void map_dst(Map *map);
  33 /*
  34         Destroys the map.
  35
  36         The map should not be used afterwards.
  37         Make sure to cancel the map before destroying it, to avoid memory leaks.
  38 */
  39
  40 void map_cnl(Map *map, void *iter, void *arg, void *trans, TreeTraversionOrder order);
  41 /*
  42         [Thread Safe]
  43         Cancels and clears the map.
  44
  45         All subsequent calls to add, get and del have no effect and return NULL.
  46
  47         Traverses the map and deletes all elements.
  48         Calls func on every element, with the extra argument arg.
  49
  50         The map is empty afterwards.
  51         If no callback is given, the traversion order is irrelevant.
  52 */
  53
  54 bool map_add(Map *map, void *key, void *dat, void *cmp, void *trans);
  55 /*
  56         [Thread Safe]
  57         Add an element to the map.
  58
  59         If an equal element is already in the map, don't add anything.
  60         Return whether an element has been added.
  61 */
  62
  63 void *map_get(Map *map, void *key, void *cmp, void *trans);
  64 /*
  65         [Thread Safe]
  66         Get an element from the map, or return NULL if none found.
  67 */
  68
  69 bool map_del(Map *map, void *key, void *cmp, void *call, void *arg, void *trans);
  70 /*
  71         [Thread Safe]
  72         Delete an element from the map if it is found.
  73         Return whether an element has been deleted.
  74 */
  75
  76 void map_trv(Map *map, void *iter, void *arg, void *trans, TreeTraversionOrder order);
  77 /*
  78         [Thread Safe]
  79         Traverse the map.
  80         Calls iter on every element, with the extra argument arg.
  81 */
  82
  83
  84 #endif