All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
modules/common/target/Linux-x86_64/include/aerospike/as_rec.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <aerospike/as_integer.h>
26 #include <aerospike/as_bytes.h>
27 #include <aerospike/as_list.h>
28 #include <aerospike/as_map.h>
29 #include <aerospike/as_string.h>
30 #include <aerospike/as_util.h>
31 #include <aerospike/as_val.h>
32 
33 #include <stdbool.h>
34 #include <stdint.h>
35 
36 /******************************************************************************
37  * TYPES
38  *****************************************************************************/
39 
40 struct as_rec_hooks_s;
41 
42 /**
43  * Callback function for `as_rec_foreach()`. Called for each bin in the
44  * record.
45  *
46  * @param name The name of the current bin.
47  * @param value The value of the current bin.
48  * @param udata The user-data provided to the `as_rec_foreach()`.
49  *
50  * @return true to continue iterating through the list.
51  * false to stop iterating.
52  */
53 typedef bool (* as_rec_foreach_callback) (const char * name, const as_val * value, void * udata);
54 
55 /**
56  * as_rec is an interface for record types. A record is how data in Aerospike
57  * is represented, and is composed of bins and metadata.
58  *
59  * Implementations:
60  * - as_record
61  *
62  * @extends as_val
63  * @ingroup aerospike_t
64  */
65 typedef struct as_rec_s {
66 
67  /**
68  * @private
69  * as_boolean is a subtype of as_val.
70  * You can cast as_boolean to as_val.
71  */
72  as_val _;
73 
74  /**
75  * Data provided by the implementation of `as_rec`.
76  */
77  void * data;
78 
79  /**
80  * Hooks provided by the implementation of `as_rec`.
81  */
82  const struct as_rec_hooks_s * hooks;
83 
84 } as_rec;
85 
86 /**
87  * Record Hooks.
88  *
89  * An implementation of `as_rec` should provide implementations for each
90  * of the hooks.
91  */
92 typedef struct as_rec_hooks_s {
93 
94  /**
95  * Destroy the record.
96  */
97  bool (* destroy)(as_rec * rec);
98 
99  /**
100  * Get the hashcode of the record.
101  */
102  uint32_t (* hashcode)(const as_rec * rec);
103 
104  /**
105  * Get the value of the bin in the record.
106  */
107  as_val * (* get)(const as_rec * rec, const char * name);
108 
109  /**
110  * Set the value of the bin in the record.
111  */
112  int (* set)(const as_rec * rec, const char * name, const as_val * value);
113 
114  /**
115  * Remove the bin from the record.
116  */
117  int (* remove)(const as_rec * rec, const char * bin);
118 
119  /**
120  * Get the ttl value of the record.
121  */
122  uint32_t (* ttl)(const as_rec * rec);
123 
124  /**
125  * Get the generation value of the record.
126  */
127  uint16_t (* gen)(const as_rec * rec);
128 
129  /**
130  * Get the number of bins of the record.
131  */
132  uint16_t (* numbins)(const as_rec * rec);
133 
134  /**
135  * Get the digest of the record.
136  */
137  as_bytes * (* digest)(const as_rec * rec);
138 
139  /**
140  * Set flags on a bin.
141  */
142  int (* set_flags)(const as_rec * rec, const char * bin, uint8_t flags);
143 
144  /**
145  * Set the type of record.
146  */
147  int (* set_type)(const as_rec * rec, uint8_t type);
148 
149  /**
150  * Iterate over each bin in the record.
151  */
152  bool (* foreach)(const as_rec * rec, as_rec_foreach_callback callback, void * udata);
153 
154 } as_rec_hooks;
155 
156 /******************************************************************************
157  * INSTANCE FUNCTIONS
158  *****************************************************************************/
159 
160 /**
161  * @private
162  * Utilized by subtypes of as_rec to initialize the parent.
163  *
164  * @param rec The record to initialize
165  * @param free If TRUE, then as_rec_destory() will free the record.
166  * @param data Data for the map.
167  * @param hooks Implementation for the map interface.
168  *
169  * @return The initialized as_map on success. Otherwise NULL.
170  *
171  * @relatesalso as_rec
172  */
173 as_rec * as_rec_cons(as_rec * rec, bool free, void * data, const as_rec_hooks * hooks);
174 
175 /**
176  * Initialize a stack allocated record.
177  *
178  * @param rec Stack allocated record to initialize.
179  * @param data Data for the record.
180  * @param hooks Implementation for the record interface.
181  *
182  * @return On success, the initialized record. Otherwise NULL.
183  *
184  * @relatesalso as_rec
185  */
186 as_rec * as_rec_init(as_rec * rec, void * data, const as_rec_hooks * hooks);
187 
188 /**
189  * Create and initialize a new heap allocated record.
190  *
191  * @param data Data for the record.
192  * @param hooks Implementation for the record interface.
193  *
194  * @return On success, a new record. Otherwise NULL.
195  *
196  * @relatesalso as_rec
197  */
198 as_rec * as_rec_new(void * data, const as_rec_hooks * hooks);
199 
200 /**
201  * Destroy the record.
202  *
203  * @relatesalso as_rec
204  */
205 static inline void as_rec_destroy(as_rec * rec)
206 {
207  as_val_destroy((as_val *) rec);
208 }
209 
210 /******************************************************************************
211  * INLINE FUNCTIONS
212  ******************************************************************************/
213 
214 /**
215  * Get the data source for the record.
216  *
217  * @relatesalso as_rec
218  */
219 static inline void * as_rec_source(const as_rec * rec)
220 {
221  return rec ? rec->data : NULL;
222 }
223 
224 /**
225  * Remove a bin from a record.
226  *
227  * @param rec The record to remove the bin from.
228  * @param name The name of the bin to remove.
229  *
230  * @return 0 on success, otherwise an error occurred.
231  *
232  * @relatesalso as_rec
233  */
234 static inline int as_rec_remove(const as_rec * rec, const char * name)
235 {
236  return as_util_hook(remove, 1, rec, name);
237 }
238 
239 /**
240  * Get the ttl for the record.
241  *
242  * @relatesalso as_rec
243  */
244 static inline uint32_t as_rec_ttl(const as_rec * rec)
245 {
246  return as_util_hook(ttl, 0, rec);
247 }
248 
249 /**
250  * Get the generation of the record
251  *
252  * @relatesalso as_rec
253  */
254 static inline uint16_t as_rec_gen(const as_rec * rec)
255 {
256  return as_util_hook(gen, 0, rec);
257 }
258 
259 /**
260  * Get the number of bins in the record.
261  *
262  * @relatesalso as_rec
263  */
264 static inline uint16_t as_rec_numbins(const as_rec * rec)
265 {
266  return as_util_hook(numbins, 0, rec);
267 }
268 
269 /**
270  * Get the digest of the record.
271  *
272  * @relatesalso as_rec
273  */
274 static inline as_bytes * as_rec_digest(const as_rec * rec)
275 {
276  return as_util_hook(digest, 0, rec);
277 }
278 
279 /**
280  * Set flags on a bin.
281  *
282  * @relatesalso as_rec
283  */
284 static inline int as_rec_set_flags(const as_rec * rec, const char * name, uint8_t flags)
285 {
286  return as_util_hook(set_flags, 0, rec, name, flags);
287 }
288 
289 /**
290  * Set the record type.
291  *
292  * @relatesalso as_rec
293  */
294 static inline int as_rec_set_type(const as_rec * rec, uint8_t rec_type)
295 {
296  return as_util_hook(set_type, 0, rec, rec_type);
297 }
298 
299 /******************************************************************************
300  * BIN GETTER FUNCTIONS
301  ******************************************************************************/
302 
303 /**
304  * Get a bin's value.
305  *
306  * @param rec The as_rec to read the bin value from.
307  * @param name The name of the bin.
308  *
309  * @return On success, the value of the bin. Otherwise NULL.
310  *
311  * @relatesalso as_rec
312  */
313 static inline as_val * as_rec_get(const as_rec * rec, const char * name)
314 {
315  return as_util_hook(get, NULL, rec, name);
316 }
317 
318 /**
319  * Get a bin's value as an int64_t.
320  *
321  * @param rec The as_rec to read the bin value from.
322  * @param name The name of the bin.
323  *
324  * @return On success, the value of the bin. Otherwise 0.
325  *
326  * @relatesalso as_rec
327  */
328 static inline int64_t as_rec_get_int64(const as_rec * rec, const char * name)
329 {
330  as_val * v = as_util_hook(get, NULL, rec, name);
332  return i ? as_integer_toint(i) : 0;
333 }
334 
335 /**
336  * Get a bin's value as a NULL terminated string.
337  *
338  * @param rec The as_rec to read the bin value from.
339  * @param name The name of the bin.
340  *
341  * @return On success, the value of the bin. Otherwise NULL.
342  *
343  * @relatesalso as_rec
344  */
345 static inline char * as_rec_get_str(const as_rec * rec, const char * name)
346 {
347  as_val * v = as_util_hook(get, NULL, rec, name);
348  as_string * s = as_string_fromval(v);
349  return s ? as_string_tostring(s) : 0;
350 }
351 
352 /**
353  * Get a bin's value as an as_integer.
354  *
355  * @param rec The as_rec to read the bin value from.
356  * @param name The name of the bin.
357  *
358  * @return On success, the value of the bin. Otherwise NULL.
359  *
360  * @relatesalso as_rec
361  */
362 static inline as_integer * as_rec_get_integer(const as_rec * rec, const char * name)
363 {
364  as_val * v = as_util_hook(get, NULL, rec, name);
365  return as_integer_fromval(v);
366 }
367 
368 /**
369  * Get a bin's value as an as_string.
370  *
371  * @param rec The as_rec to read the bin value from.
372  * @param name The name of the bin.
373  *
374  * @return On success, the value of the bin. Otherwise NULL.
375  *
376  * @relatesalso as_rec
377  */
378 static inline as_string * as_rec_get_string(const as_rec * rec, const char * name)
379 {
380  as_val * v = as_util_hook(get, NULL, rec, name);
381  return as_string_fromval(v);
382 }
383 
384 /**
385  * Get a bin's value as an as_bytes.
386  *
387  * @param rec The as_rec to read the bin value from.
388  * @param name The name of the bin.
389  *
390  * @return On success, the value of the bin. Otherwise NULL.
391  *
392  * @relatesalso as_rec
393  */
394 static inline as_bytes * as_rec_get_bytes(const as_rec * rec, const char * name)
395 {
396  as_val * v = as_util_hook(get, NULL, rec, name);
397  return as_bytes_fromval(v);
398 }
399 
400 /**
401  * Get a bin's value as an as_list.
402  *
403  * @param rec The as_rec to read the bin value from.
404  * @param name The name of the bin.
405  *
406  * @return On success, the value of the bin. Otherwise NULL.
407  *
408  * @relatesalso as_rec
409  */
410 static inline as_list * as_rec_get_list(const as_rec * rec, const char * name)
411 {
412  as_val * v = as_util_hook(get, NULL, rec, name);
413  return as_list_fromval(v);
414 }
415 
416 /**
417  * Get a bin's value as an as_map.
418  *
419  * @param rec The as_rec to read the bin value from.
420  * @param name The name of the bin.
421  *
422  * @return On success, the value of the bin. Otherwise NULL.
423  *
424  * @relatesalso as_rec
425  */
426 static inline as_map * as_rec_get_map(const as_rec * rec, const char * name)
427 {
428  as_val * v = as_util_hook(get, NULL, rec, name);
429  return as_map_fromval(v);
430 }
431 
432 /******************************************************************************
433  * BIN SETTER FUNCTIONS
434  ******************************************************************************/
435 
436 /**
437  * Set the bin's value to an as_val.
438  *
439  * @param rec The as_rec to write the bin value to - CONSUMES REFERENCE
440  * @param name The name of the bin.
441  * @param value The value of the bin.
442  *
443  * @return On success, 0. Otherwise an error occurred.
444  *
445  * @relatesalso as_rec
446  */
447 static inline int as_rec_set(const as_rec * rec, const char * name, const as_val * value)
448 {
449  return as_util_hook(set, 1, rec, name, value);
450 }
451 
452 /**
453  * Set the bin's value to an int64_t.
454  *
455  * @param rec The as_rec storing the bin.
456  * @param name The name of the bin.
457  * @param value The value of the bin.
458  *
459  * @return On success, 0. Otherwise an error occurred.
460  *
461  * @relatesalso as_rec
462  */
463 static inline int as_rec_set_int64(const as_rec * rec, const char * name, int64_t value)
464 {
465  return as_util_hook(set, 1, rec, name, (as_val *) as_integer_new(value));
466 }
467 
468 /**
469  * Set the bin's value to a NULL terminated string.
470  *
471  * @param rec The as_rec storing the bin.
472  * @param name The name of the bin.
473  * @param value The value of the bin.
474  *
475  * @return On success, 0. Otherwise an error occurred.
476  *
477  * @relatesalso as_rec
478  */
479 static inline int as_rec_set_str(const as_rec * rec, const char * name, const char * value)
480 {
481  return as_util_hook(set, 1, rec, name, (as_val *) as_string_new_strdup(value));
482 }
483 
484 /**
485  * Set the bin's value to an as_integer.
486  *
487  * @param rec The as_rec storing the bin.
488  * @param name The name of the bin.
489  * @param value The value of the bin.
490  *
491  * @return On success, 0. Otherwise an error occurred.
492  *
493  * @relatesalso as_rec
494  */
495 static inline int as_rec_set_integer(const as_rec * rec, const char * name, const as_integer * value)
496 {
497  return as_util_hook(set, 1, rec, name, (as_val *) value);
498 }
499 
500 /**
501  * Set the bin's value to an as_string.
502  *
503  * @param rec The as_rec storing the bin.
504  * @param name The name of the bin.
505  * @param value The value of the bin.
506  *
507  * @return On success, 0. Otherwise an error occurred.
508  *
509  * @relatesalso as_rec
510  */
511 static inline int as_rec_set_string(const as_rec * rec, const char * name, const as_string * value)
512 {
513  return as_util_hook(set, 1, rec, name, (as_val *) value);
514 }
515 
516 /**
517  * Set the bin's value to an as_bytes.
518  *
519  * @param rec The as_rec storing the bin.
520  * @param name The name of the bin.
521  * @param value The value of the bin.
522  *
523  * @return On success, 0. Otherwise an error occurred.
524  *
525  * @relatesalso as_rec
526  */
527 static inline int as_rec_set_bytes(const as_rec * rec, const char * name, const as_bytes * value)
528 {
529  return as_util_hook(set, 1, rec, name, (as_val *) value);
530 }
531 
532 /**
533  * Set the bin's value to an as_list.
534  *
535  * @param rec The as_rec storing the bin.
536  * @param name The name of the bin.
537  * @param value The value of the bin.
538  *
539  * @return On success, 0. Otherwise an error occurred.
540  *
541  * @relatesalso as_rec
542  */
543 static inline int as_rec_set_list(const as_rec * rec, const char * name, const as_list * value)
544 {
545  return as_util_hook(set, 1, rec, name, (as_val *) value);
546 }
547 
548 /**
549  * Set the bin's value to an as_map.
550  *
551  * @param rec The as_rec storing the bin.
552  * @param name The name of the bin.
553  * @param value The value of the bin.
554  *
555  * @return On success, 0. Otherwise an error occurred.
556  *
557  * @relatesalso as_rec
558  */
559 static inline int as_rec_set_map(const as_rec * rec, const char * name, const as_map * value)
560 {
561  return as_util_hook(set, 1, rec, name, (as_val *) value);
562 }
563 
564 /******************************************************************************
565  * ITERATION FUNCTIONS
566  ******************************************************************************/
567 
568 /**
569  * Call the callback function for each bin in the record.
570  *
571  * @param rec The as_rec containing the bins to iterate over.
572  * @param callback The function to call for each entry.
573  * @param udata User-data to be passed to the callback.
574  *
575  * @return true if iteration completes fully. false if iteration was aborted.
576  *
577  * @relatesalso as_rec
578  */
579 static inline bool as_rec_foreach(const as_rec * rec, as_rec_foreach_callback callback, void * udata)
580 {
581  return as_util_hook(foreach, false, rec, callback, udata);
582 }
583 
584 /******************************************************************************
585  * CONVERSION FUNCTIONS
586  ******************************************************************************/
587 
588 /**
589  * Convert to an as_val.
590  *
591  * @relatesalso as_rec
592  */
593 static inline as_val * as_rec_toval(const as_rec * rec)
594 {
595  return (as_val *) rec;
596 }
597 
598 /**
599  * Convert from an as_val.
600  *
601  * @relatesalso as_rec
602  */
603 static inline as_rec * as_rec_fromval(const as_val * v)
604 {
605  return as_util_fromval(v, AS_REC, as_rec);
606 }
607 
608 /******************************************************************************
609  * as_val FUNCTIONS
610  ******************************************************************************/
611 
612 /**
613  * @private
614  * Internal helper function for destroying an as_val.
615  */
616 void as_rec_val_destroy(as_val *);
617 
618 /**
619  * @private
620  * Internal helper function for getting the hashcode of an as_val.
621  */
622 uint32_t as_rec_val_hashcode(const as_val *v);
623 
624 /**
625  * @private
626  * Internal helper function for getting the string representation of an as_val.
627  */
628 char * as_rec_val_tostring(const as_val *v);
static as_integer * as_integer_fromval(const as_val *v)
static uint32_t as_rec_ttl(const as_rec *rec)
as_rec * as_rec_cons(as_rec *rec, bool free, void *data, const as_rec_hooks *hooks)
static as_map * as_rec_get_map(const as_rec *rec, const char *name)
uint32_t as_rec_val_hashcode(const as_val *v)
static as_list * as_rec_get_list(const as_rec *rec, const char *name)
as_rec * as_rec_init(as_rec *rec, void *data, const as_rec_hooks *hooks)
static int64_t as_integer_toint(const as_integer *integer)
static int as_rec_set(const as_rec *rec, const char *name, const as_val *value)
char * as_rec_val_tostring(const as_val *v)
void as_rec_val_destroy(as_val *)
static as_bytes * as_rec_get_bytes(const as_rec *rec, const char *name)
as_integer * as_integer_new(int64_t value)
static bool as_rec_foreach(const as_rec *rec, as_rec_foreach_callback callback, void *udata)
static int64_t as_rec_get_int64(const as_rec *rec, const char *name)
static as_val * as_rec_get(const as_rec *rec, const char *name)
static char * as_rec_get_str(const as_rec *rec, const char *name)
static int as_rec_remove(const as_rec *rec, const char *name)
static void as_rec_destroy(as_rec *rec)
static uint16_t as_rec_numbins(const as_rec *rec)
#define as_util_fromval(object, type_id, type)
static as_string * as_rec_get_string(const as_rec *rec, const char *name)
static as_rec * as_rec_fromval(const as_val *v)
static int as_rec_set_list(const as_rec *rec, const char *name, const as_list *value)
static int as_rec_set_int64(const as_rec *rec, const char *name, int64_t value)
bool(* as_rec_foreach_callback)(const char *name, const as_val *value, void *udata)
static as_bytes * as_bytes_fromval(const as_val *v)
static int as_rec_set_bytes(const as_rec *rec, const char *name, const as_bytes *value)
static char * as_string_tostring(const as_string *string)
static as_string * as_string_fromval(const as_val *v)
static int as_rec_set_type(const as_rec *rec, uint8_t rec_type)
as_string * as_string_new_strdup(const char *value)
static as_list * as_list_fromval(as_val *v)
static int as_rec_set_flags(const as_rec *rec, const char *name, uint8_t flags)
static void * as_rec_source(const as_rec *rec)
static as_bytes * as_rec_digest(const as_rec *rec)
static as_map * as_map_fromval(const as_val *val)
static int as_rec_set_str(const as_rec *rec, const char *name, const char *value)
static int as_rec_set_string(const as_rec *rec, const char *name, const as_string *value)
static uint16_t as_rec_gen(const as_rec *rec)
#define as_util_hook(hook, default, object, args...)
static int as_rec_set_integer(const as_rec *rec, const char *name, const as_integer *value)
static int as_rec_set_map(const as_rec *rec, const char *name, const as_map *value)
as_rec * as_rec_new(void *data, const as_rec_hooks *hooks)
static as_integer * as_rec_get_integer(const as_rec *rec, const char *name)
static as_val * as_rec_toval(const as_rec *rec)