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