source3/rpc_server/mdssvc/dalloc.h

   1 /*
   2    Copyright (c) Ralph Boehme                   2012-2014
   3
   4    This program is free software; you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation; either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16 */
  17
  18 /*
  19   Typesafe, dynamic object store based on talloc
  20
  21   Usage
  22   =====
  23
  24   Define some types:
  25
  26   A key/value store aka dictionary that supports retrieving elements
  27   by key:
  28
  29     typedef dict_t DALLOC_CTX;
  30
  31   An ordered set that can store different objects which can be
  32   retrieved by number:
  33
  34     typedef set_t DALLOC_CTX;
  35
  36   Create an dalloc object and add elementes of different type:
  37
  38     TALLOC_CTX *mem_ctx = talloc_new(NULL);
  39     DALLOC_CTX *d = dalloc_new(mem_ctx);
  40
  41   Store an int value in the object:
  42
  43     uint64_t i = 1;
  44     dalloc_add_copy(d, &i, uint64_t);
  45
  46   Store a string:
  47
  48     dalloc_stradd(d, "hello world");
  49
  50   Add a nested object:
  51
  52     DALLOC_CTX *nested = dalloc_new(d);
  53     dalloc_add(d, nested, DALLOC_CTX);
  54
  55   Add an int value to the nested object, this can be fetched:
  56
  57     i = 2;
  58     dalloc_add_copy(nested, &i, uint64_t);
  59
  60   Add a nested set:
  61
  62     set_t *set = dalloc_zero(nested, set_t);
  63     dalloc_add(nested, set, set_t);
  64
  65   Add an int value to the set:
  66
  67     i = 3;
  68     dalloc_add_copy(set, &i, uint64_t);
  69
  70   Add a dictionary (key/value store):
  71
  72     dict_t *dict = dalloc_zero(nested, dict_t);
  73     dalloc_add(nested, dict, dict_t);
  74
  75   Store a string as key in the dict:
  76
  77     dalloc_stradd(dict, "key");
  78
  79   Add a value for the key:
  80
  81     i = 4;
  82     dalloc_add_copy(dict, &i, uint64_t);
  83
  84   Fetching value references
  85   =========================
  86
  87   You can fetch anything that is not a DALLOC_CTXs, because passing
  88   "DALLOC_CTXs" as type to the functions dalloc_get() and
  89   dalloc_value_for_key() tells the function to step into that object
  90   and expect more arguments that specify which element to fetch.
  91
  92   Get reference to an objects element by position:
  93
  94     uint64_t *p = dalloc_get(d, "uint64_t", 0);
  95
  96   p now points to the first int with a value of 1.
  97
  98   Get reference to the "hello world" string:
  99
 100     str = dalloc_get(d, "char *", 1);
 101
 102   You can't fetch a DALLOC_CTX itself:
 103
 104     nested = dalloc_get(d, "DALLOC_CTX", 2);
 105
 106   But you can fetch elements from the nested DALLOC_CTX:
 107
 108     p = dalloc_get(d, "DALLOC_CTX", 2, "uint64_t", 0);
 109
 110   p now points to the value 2.
 111
 112   You can fetch types that are typedefd DALLOC_CTXs:
 113
 114     set = dalloc_get(d, "DALLOC_CTX", 2, "set_t", 1);
 115
 116   Fetch int from set, must use DALLOC_CTX as type for the set:
 117
 118     p = dalloc_get(d, "DALLOC_CTX", 2, "DALLOC_CTX", 1, "uint64_t", 0);
 119
 120   p points to 3.
 121
 122   Fetch value by key from dictionary:
 123
 124     p = dalloc_value_for_key(d, "DALLOC_CTX", 2, "DALLOC_CTX", 2, "key");
 125
 126   p now points to 4.
 127 */
 128
 129 #ifndef DALLOC_H
 130 #define DALLOC_H
 131
 132 #include <talloc.h>
 133
 134 struct dalloc_ctx;
 135 typedef struct dalloc_ctx DALLOC_CTX;
 136
 137 #define dalloc_new(mem_ctx) (DALLOC_CTX *)_dalloc_new((mem_ctx), "DALLOC_CTX")
 138 #define dalloc_zero(mem_ctx, type) (type *)_dalloc_new((mem_ctx), #type)
 139
 140 /**
 141  * talloc a chunk for obj of required size, copy the obj into the
 142  * chunk and add the chunk to the dalloc ctx
 143  **/
 144 #define dalloc_add_copy(d, obj, type) _dalloc_add_talloc_chunk((d), (obj), #type, sizeof(type))
 145
 146 /**
 147  * Add a pointer to a talloced object to the dalloc ctx. The object
 148  * must be a talloc child of the dalloc ctx.
 149  **/
 150 #define dalloc_add(d, obj, type) _dalloc_add_talloc_chunk((d), (obj), #type, 0)
 151
 152
 153 extern void *dalloc_get(const DALLOC_CTX *d, ...);
 154 extern void *dalloc_value_for_key(const DALLOC_CTX *d, ...);
 155 extern size_t dalloc_size(const DALLOC_CTX *d);
 156 extern void *dalloc_get_object(const DALLOC_CTX *d, int i);
 157 extern const char *dalloc_get_name(const DALLOC_CTX *d, int i);
 158 extern int dalloc_stradd(DALLOC_CTX *d, const char *string);
 159
 160 extern void *_dalloc_new(TALLOC_CTX *mem_ctx, const char *type);
 161 extern int _dalloc_add_talloc_chunk(DALLOC_CTX *d, void *obj, const char *type, size_t size);
 162
 163 #endif  /* DALLOC_H */