include/xbt/lib.h

   1 /* xbt/lib.h - api to a generic library                                     */
   2
   3 /* Copyright (c) 2011, 2013-2014. The SimGrid Team.
   4  * All rights reserved.                                                     */
   5
   6 /* This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the license (GNU LGPL) which comes with this package. */
   8
   9 #ifndef _XBT_LIB_H
  10 #define _XBT_LIB_H
  11
  12 #include <xbt/dict.h>
  13
  14 SG_BEGIN_DECL()
  15
  16 /** Container for all the objects of a given type
  17  *
  18  *  * each item is identified by a string name/identifier;
  19  *
  20  *  * the lib itself is a dictionary from the element id to the element;
  21  *
  22  *  * the element itself is represented aby the xbt_dictelm_t;
  23  *
  24  *  * the element can store any number of associated facets/data structures
  25  *    (corresponding to the different layers of SimGrid or its extensions)
  26  *    in ((void**)dictelt->content)[level];
  27  *
  28  *  * each level is allocated in the lib with `xbt_lib_add_level`.
  29  *
  30  *  <pre>
  31  *  // Define a collection for the foo objects and two associated facets:
  32  *  typedef xbt_dictelm_t foo_t;
  33  *  xbt_lib_t foo_lib = xbt_lib_new();
  34  *  int BAR_FOO_LEVEL  = xbt_lib_add_level(foo_lib, free_bar);
  35  *  int AUTH_FOO_LEVEL = xbt_lib_add_level(foo_lib, free_auth);
  36  *
  37  *  // Store a bar:
  38  *  bar_t bar = bar_new();
  39  *  char* id = bar_name(bar);
  40  *  xbt_lib_set(id, id, BAR_FOO_LEVEL, bar);
  41  *
  42  *  // Find the corresponding foo and the facet again:
  43  *  foo_t foo = xbt_lib_get_elm_or_null(foo_lib, id);
  44  *  bar_t bar2 = (bar_t) xbt_lib_get_level(foo, BAR_FOO_LEVEL);
  45  *  assert(bar == bar2);
  46  *
  47  *  // Add authentication facet for the previous object:
  48  *  auth_t auth = auth_new();
  49  *  xbt_lib_set(foo_lib, id, AUTH_FOO_LEVEL, auth);
  50  *  </pre>
  51  */
  52 typedef struct s_xbt_lib {
  53   xbt_dict_t dict;
  54   int levels;
  55   void_f_pvoid_t *free_f;       /* This is actually a table */
  56 } s_xbt_lib_t, *xbt_lib_t;
  57
  58 #define xbt_lib_cursor_t xbt_dict_cursor_t
  59
  60 XBT_PUBLIC(xbt_lib_t) xbt_lib_new(void);
  61 XBT_PUBLIC(void) xbt_lib_free(xbt_lib_t * lib);
  62 XBT_PUBLIC(int) xbt_lib_add_level(xbt_lib_t lib, void_f_pvoid_t free_f);
  63 XBT_PUBLIC(void) xbt_lib_set(xbt_lib_t lib, const char *name, int level,
  64                              void *obj);
  65 XBT_PUBLIC(void) xbt_lib_unset(xbt_lib_t lib, const char *key, int level, int invoke_callback);
  66 XBT_PUBLIC(void *) xbt_lib_get_or_null(xbt_lib_t lib, const char *name,
  67                                        int level);
  68 XBT_PUBLIC(xbt_dictelm_t) xbt_lib_get_elm_or_null(xbt_lib_t lib, const char *key);
  69 XBT_PUBLIC(void *) xbt_lib_get_level(xbt_dictelm_t elm, int level);
  70 XBT_PUBLIC(void) xbt_lib_remove(xbt_lib_t lib, const char *key);
  71
  72 #define xbt_lib_length(lib) xbt_dict_length((lib)->dict)
  73
  74 /** @def xbt_lib_foreach
  75     @hideinitializer */
  76 #define xbt_lib_foreach(lib, cursor, key, data)         \
  77   xbt_dict_foreach((lib)->dict, cursor, key, data)
  78
  79 SG_END_DECL()
  80 #endif                          /* _XBT_LIB_H */