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