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