All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
as_operations.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 #pragma once
18 
19 #include <stdbool.h>
20 #include <stdint.h>
21 #include <aerospike/as_bin.h>
22 
23 /******************************************************************************
24  * TYPES
25  *****************************************************************************/
26 
27 /**
28  * Operation Identifiers
29  */
30 typedef enum as_operator_e {
31 
32  /**
33  * Update the bin.
34  */
36 
37  /**
38  * Return the bin from the cluster.
39  */
41 
42  /**
43  * Increment a bin containing an
44  * integer value.
45  */
47 
48  /**
49  * Prepend bytes to the bin containing
50  * either a string or blob.
51  */
53 
54  /**
55  * Append bytes to the bin containing
56  * either a string or blob.
57  */
59 
60  /**
61  * Touch the record's ttl.
62  */
64 
65 } as_operator;
66 
67 /**
68  * Operation on a bin.
69  * The value for the bin will be applied according to the operation.
70  */
71 typedef struct as_binop_s {
72 
73  /**
74  * The operation to be performed on the bin.
75  */
77 
78  /**
79  * The bin the operation will be performed on.
80  */
82 
83 } as_binop;
84 
85 /**
86  * Sequence of operations.
87  *
88  * ~~~~~~~~~~{.c}
89  * as_operations ops;
90  * as_operations_inita(&ops, 2);
91  * as_operations_add_incr(&ops, "bin1", 123);
92  * as_operations_add_append_str(&ops, "bin2", "abc");
93  * ...
94  * as_operations_destroy(&ops);
95  * ~~~~~~~~~~
96  *
97  */
98 typedef struct as_binops_s {
99 
100  /**
101  * @private
102  * If true, then as_binops_destroy() will free the entries.
103  */
104  bool _free;
105 
106  /**
107  * Number of entries allocated
108  */
109  uint16_t capacity;
110 
111  /**
112  * Number of entries used
113  */
114  uint16_t size;
115 
116  /**
117  * Sequence of entries
118  */
120 
121 } as_binops;
122 
123 /**
124  * The `aerospike_key_operate()` function provides the ability to execute
125  * multiple operations on a record in the database as a single atomic
126  * transaction.
127  *
128  * The `as_operations` object is used to define the operations to be performed
129  * on the record.
130  *
131  * ## Initialization
132  *
133  * Before using as_operations, you must first initialize it via either:
134  * - as_operations_inita()
135  * - as_operations_init()
136  * - as_operations_new()
137  *
138  * as_operations_inita() is a macro that initializes a stack allocated
139  * as_operations and allocates an internal array of operations. The macro
140  * accepts a pointer to the stack allocated as_operations and the number of
141  * operations to be added.
142  *
143  * ~~~~~~~~~~{.c}
144  * as_operations ops;
145  * as_operations_inita(&ops, 2);
146  * ~~~~~~~~~~
147  *
148  * as_operations_init() is a function that initializes a stack allocated
149  * as_operations. It differes from as_operations_inita() in that it allocates
150  * the internal array of operations on the heap. It accepts a pointer to the
151  * stack allocated as_operations and the number of operations to be added.
152  *
153  * ~~~~~~~~~~{.c}
154  * as_operations ops;
155  * as_operations_init(&ops, 2);
156  * ~~~~~~~~~~
157  *
158  * as_operations_new() is a function that will allocate a new as_operations
159  * on the heap. It will also allocate the internal array of operation on the
160  * heap.
161  *
162  * ~~~~~~~~~~{.c}
163  * as_operations * ops = as_operations_new(2);
164  * ~~~~~~~~~~
165  *
166  * When you no longer needthe as_operations, you can release the resources
167  * allocated to it via as_operations_destroy().
168  *
169  * ## Destruction
170  *
171  * When you no longer require an as_operations, you should call
172  * `as_operations_destroy()` to release it and associated resources.
173  *
174  * ~~~~~~~~~~{.c}
175  * as_operations_destroy(ops);
176  * ~~~~~~~~~~
177  *
178  * ## Usage
179  *
180  * as_operations is a sequence of operations to be applied to a record.
181  *
182  * Each of the following operations is added to the end of the sequence
183  * of operations.
184  *
185  * When you have compiled the sequence of operations you want to execute,
186  * then you will send it to aerospike_key_operate().
187  *
188  *
189  * ### Modifying a String
190  *
191  * Aerospike allows you to append a string to a bin containing
192  * a string.
193  *
194  * The following appends a "abc" to bin "bin1".
195  *
196  * ~~~~~~~~~~{.c}
197  * as_operations_add_append_str(ops, "bin1", "abc");
198  * ~~~~~~~~~~
199  *
200  * There is also a prepend operation, which will add the string
201  * to the beginning of the bin's current value.
202  *
203  * ~~~~~~~~~~{.c}
204  * as_operations_add_prepend_str(ops, "bin1", "abc");
205  * ~~~~~~~~~~
206  *
207  * ### Modifying a Byte Array
208  *
209  * Aerospike allows you to append a byte array to a bin containing
210  * a byte array.
211  *
212  * The following appends a 4 byte sequence to bin "bin1".
213  *
214  * ~~~~~~~~~~{.c}
215  * uint8_t raw[4] = { 1, 2, 3, 4 };
216  * as_operations_add_append_raw(ops, "bin1", raw, 4);
217  * ~~~~~~~~~~
218  *
219  * There is also a prepend operation, which will add the bytes
220  * to the beginning of the bin's current value.
221  *
222  * ~~~~~~~~~~{.c}
223  * uint8_t raw[4] = { 1, 2, 3, 4 };
224  * as_operations_add_prepend_raw(ops, "bin1", raw, 4);
225  * ~~~~~~~~~~
226  *
227  * ### Increment an Integer
228  *
229  * Aerospike allows you to increment the value of a bin
230  *
231  * The following increments the value in bin "bin1" by 4.
232  *
233  * ~~~~~~~~~~{.c}
234  * as_operations_add_incr(ops, "bin1", 4);
235  * ~~~~~~~~~~
236  *
237  * ### Write a Value
238  *
239  * Write a value into a bin. Overwriting previous value.
240  *
241  * The following writes a string "xyz" to "bin1".
242  *
243  * ~~~~~~~~~~{.c}
244  * as_operations_add_write_str(ops, "bin1", "xyz");
245  * ~~~~~~~~~~
246  *
247  * ### Read a Value
248  *
249  * Read a value from a bin. This is ideal, if you performed an
250  * operation on a bin, and want to read the new value.
251  *
252  * The following reads the value of "bin1"
253  *
254  * ~~~~~~~~~~{.c}
255  * as_operations_add_read(ops, "bin1", "xyz");
256  * ~~~~~~~~~~
257  *
258  * ### Touch a Record
259  *
260  * Touching a record will refresh its ttl and increment the generation
261  * of the record.
262  *
263  * The following touches a record.
264  *
265  * ~~~~~~~~~~{.c}
266  * as_operations_add_touch(ops);
267  * ~~~~~~~~~~
268  *
269  * @ingroup client_objects
270  */
271 typedef struct as_operations_s {
272 
273  /**
274  * @private
275  * If true, then as_operations_destroy() will free this instance.
276  */
277  bool _free;
278 
279  /**
280  * The generation of the record.
281  */
282  uint16_t gen;
283 
284  /**
285  * The time-to-live (expiration) of the record in seconds.
286  */
287  uint32_t ttl;
288 
289  /**
290  * Operations to be performed on the bins of a record.
291  */
293 
294 } as_operations;
295 
296 /******************************************************************************
297  * MACROS
298  *****************************************************************************/
299 
300 /**
301  * Initializes a stack allocated `as_operations` (as_operations) and allocates
302  * `__nops` number of entries on the stack.
303  *
304  * ~~~~~~~~~~{.c}
305  * as_operations ops;
306  * as_operations_inita(&ops, 2);
307  * as_operations_add_incr(&ops, "bin1", 123);
308  * as_operations_add_append_str(&ops, "bin2", "abc");
309  * ~~~~~~~~~~
310  *
311  * @param __ops The `as_operations *` to initialize.
312  * @param __nops The number of `as_binops.entries` to allocate on the
313  * stack.
314  *
315  * @relates as_operations
316  * @ingroup as_operations_object
317  */
318 #define as_operations_inita(__ops, __nops) \
319  (__ops)->_free = false;\
320  (__ops)->gen = 0;\
321  (__ops)->ttl = 0;\
322  (__ops)->binops._free = false;\
323  (__ops)->binops.capacity = __nops;\
324  (__ops)->binops.size = 0;\
325  (__ops)->binops.entries = (as_binop *) alloca(sizeof(as_binop) * __nops);
326 
327 /******************************************************************************
328  * FUNCTIONS
329  *****************************************************************************/
330 
331 /**
332  * Intializes a stack allocated `as_operations`.
333  *
334  * ~~~~~~~~~~{.c}
335  * as_operations ops;
336  * as_operations_init(&ops, 2);
337  * as_operations_add_incr(&ops, "bin1", 123);
338  * as_operations_add_append_str(&ops, "bin2", "abc");
339  * ~~~~~~~~~~
340  *
341  * Use `as_operations_destroy()` to free the resources allocated to the
342  * `as_operations`.
343  *
344  * @param ops The `as_operations` to initialize.
345  * @param nops The number of `as_operations.binops.entries` to allocate on the heap.
346  *
347  * @return The initialized `as_operations` on success. Otherwise NULL.
348  *
349  * @relates as_operations
350  * @ingroup as_operations_object
351  */
352 as_operations * as_operations_init(as_operations * ops, uint16_t nops);
353 
354 /**
355  * Create and initialize a heap allocated `as_operations`.
356  *
357  * ~~~~~~~~~~{.c}
358  * as_operations ops = as_operations_new(2);
359  * as_operations_add_incr(ops, "bin1", 123);
360  * as_operations_add_append_str(ops, "bin2", "abc");
361  * ~~~~~~~~~~
362  *
363  * Use `as_operations_destroy()` to free the resources allocated to the
364  * `as_operations`.
365  *
366  * @param nops The number of `as_operations.binops.entries` to allocate on the heap.
367  *
368  * @return The new `as_operations` on success. Otherwise NULL.
369  *
370  * @relates as_operations
371  * @ingroup as_operations_object
372  */
373 as_operations * as_operations_new(uint16_t nops);
374 
375 /**
376  * Destroy an `as_operations` and release associated resources.
377  *
378  * ~~~~~~~~~~{.c}
379  * as_operations_destroy(binops);
380  * ~~~~~~~~~~
381  *
382  * @param ops The `as_operations` to destroy.
383  *
384  * @relates as_operations
385  * @ingroup as_operations_object
386  */
388 
389 /**
390  * Add a `AS_OPERATOR_WRITE` bin operation.
391  *
392  * @param ops The `as_operations` to append the operation to.
393  * @param name The name of the bin to perform the operation on.
394  * @param value The value to be used in the operation.
395  *
396  * @return true on success. Otherwise an error occurred.
397  *
398  * @relates as_operations
399  * @ingroup as_operations_object
400  */
401 bool as_operations_add_write(as_operations * ops, const as_bin_name name, as_bin_value * value);
402 
403 /**
404  * Add a `AS_OPERATOR_WRITE` bin operation with an int64_t value.
405  *
406  * @param ops The `as_operations` to append the operation to.
407  * @param name The name of the bin to perform the operation on.
408  * @param value The value to be used in the operation.
409  *
410  * @return true on success. Otherwise an error occurred.
411  *
412  * @relates as_operations
413  * @ingroup as_operations_object
414  */
415 bool as_operations_add_write_int64(as_operations * ops, const as_bin_name name, int64_t value);
416 
417 /**
418  * Add a `AS_OPERATOR_WRITE` bin operation with a NULL-terminated string value.
419  *
420  * @param ops The `as_operations` to append the operation to.
421  * @param name The name of the bin to perform the operation on.
422  * @param value The value to be used in the operation.
423  * @param free If true, then the value will be freed when the operations is destroyed.
424  *
425  * @return true on success. Otherwise an error occurred.
426  *
427  * @relates as_operations
428  * @ingroup as_operations_object
429  */
430 bool as_operations_add_write_strp(as_operations * ops, const as_bin_name name, const char * value, bool free);
431 
432 /**
433  * Add a `AS_OPERATOR_WRITE` bin operation with a NULL-terminated string value.
434  *
435  * @param ops The `as_operations` to append the operation to.
436  * @param name The name of the bin to perform the operation on.
437  * @param value The value to be used in the operation. Must last for the lifetime of the operations.
438  *
439  * @return true on success. Otherwise an error occurred.
440  *
441  * @relates as_operations
442  * @ingroup as_operations_object
443  */
444 static inline bool as_operations_add_write_str(as_operations * ops, const as_bin_name name, const char * value)
445 {
446  return as_operations_add_write_strp(ops, name, value, false);
447 }
448 
449 /**
450  * Add a `AS_OPERATOR_WRITE` bin operation with a raw bytes value.
451  *
452  * @param ops The `as_operations` to append the operation to.
453  * @param name The name of the bin to perform the operation on.
454  * @param value The value to be used in the operation.
455  * @param size The size of the value.
456  * @param free If true, then the value will be freed when the operations is destroyed.
457  *
458  * @return true on success. Otherwise an error occurred.
459  *
460  * @relates as_operations
461  * @ingroup as_operations_object
462  */
463 bool as_operations_add_write_rawp(as_operations * ops, const as_bin_name name, const uint8_t * value, uint32_t size, bool free);
464 
465 /**
466  * Add a `AS_OPERATOR_WRITE` bin operation with a raw bytes value.
467  *
468  * @param ops The `as_operations` to append the operation to.
469  * @param name The name of the bin to perform the operation on.
470  * @param value The value to be used in the operation.
471  * @param size The size of the value. Must last for the lifetime of the operations.
472  *
473  * @return true on success. Otherwise an error occurred.
474  *
475  * @relates as_operations
476  * @ingroup as_operations_object
477  */
478 static inline bool as_operations_add_write_raw(as_operations * ops, const as_bin_name name, const uint8_t * value, uint32_t size)
479 {
480  return as_operations_add_write_rawp(ops, name, value, size, false);
481 }
482 
483 /**
484  * Add a `AS_OPERATOR_READ` bin operation.
485  *
486  * @param ops The `as_operations` to append the operation to.
487  * @param name The name of the bin to perform the operation on.
488  *
489  * @return true on success. Otherwise an error occurred.
490  *
491  * @relates as_operations
492  * @ingroup as_operations_object
493  */
494 bool as_operations_add_read(as_operations * ops, const as_bin_name name);
495 
496 /**
497  * Add a `AS_OPERATOR_INCR` bin operation with (required) int64_t value.
498  *
499  * @param ops The `as_operations` to append the operation to.
500  * @param name The name of the bin to perform the operation on.
501  * @param value The value to be used in the operation.
502  *
503  * @return true on success. Otherwise an error occurred.
504  *
505  * @relates as_operations
506  * @ingroup as_operations_object
507  */
508 bool as_operations_add_incr(as_operations * ops, const as_bin_name name, int64_t value);
509 
510 /**
511  * Add a `AS_OPERATOR_PREPEND` bin operation with a NULL-terminated string value.
512  *
513  * @param ops The `as_operations` to append the operation to.
514  * @param name The name of the bin to perform the operation on.
515  * @param value The value to be used in the operation.
516  * @param free If true, then the value will be freed when the operations is destroyed.
517  *
518  * @return true on success. Otherwise an error occurred.
519  *
520  * @relates as_operations
521  * @ingroup as_operations_object
522  */
523 bool as_operations_add_prepend_strp(as_operations * ops, const as_bin_name name, const char * value, bool free);
524 
525 /**
526  * Add a `AS_OPERATOR_PREPEND` bin operation with a NULL-terminated string value.
527  *
528  * @param ops The `as_operations` to append the operation to.
529  * @param name The name of the bin to perform the operation on.
530  * @param value The value to be used in the operation. Must last for the lifetime of the operations.
531  *
532  * @return true on success. Otherwise an error occurred.
533  *
534  * @relates as_operations
535  * @ingroup as_operations_object
536  */
537 static inline bool as_operations_add_prepend_str(as_operations * ops, const as_bin_name name, const char * value)
538 {
539  return as_operations_add_prepend_strp(ops, name, value, false);
540 }
541 
542 /**
543  * Add a `AS_OPERATOR_PREPEND` bin operation with a raw bytes value.
544  *
545  * @param ops The `as_operations` to append the operation to.
546  * @param name The name of the bin to perform the operation on.
547  * @param value The value to be used in the operation.
548  * @param size The size of the value.
549  * @param free If true, then the value will be freed when the operations is destroyed.
550  *
551  * @return true on success. Otherwise an error occurred.
552  *
553  * @relates as_operations
554  * @ingroup as_operations_object
555  */
556 bool as_operations_add_prepend_rawp(as_operations * ops, const as_bin_name name, const uint8_t * value, uint32_t size, bool free);
557 
558 /**
559  * Add a `AS_OPERATOR_PREPEND` bin operation with a raw bytes value.
560  *
561  * @param ops The `as_operations` to append the operation to.
562  * @param name The name of the bin to perform the operation on.
563  * @param value The value to be used in the operation. Must last for the lifetime of the operations.
564  * @param size The size of the value.
565  *
566  * @return true on success. Otherwise an error occurred.
567  *
568  * @relates as_operations
569  * @ingroup as_operations_object
570  */
571 static inline bool as_operations_add_prepend_raw(as_operations * ops, const as_bin_name name, const uint8_t * value, uint32_t size)
572 {
573  return as_operations_add_prepend_rawp(ops, name, value, size, false);
574 }
575 
576 /**
577  * Add a `AS_OPERATOR_APPEND` bin operation with a NULL-terminated string value.
578  *
579  * @param ops The `as_operations` to append the operation to.
580  * @param name The name of the bin to perform the operation on.
581  * @param value The value to be used in the operation.
582  * @param free If true, then the value will be freed when the operations is destroyed.
583  *
584  * @return true on success. Otherwise an error occurred.
585  *
586  * @relates as_operations
587  * @ingroup as_operations_object
588  */
589 bool as_operations_add_append_strp(as_operations * ops, const as_bin_name name, const char * value, bool free);
590 
591 /**
592  * Add a `AS_OPERATOR_APPEND` bin operation with a NULL-terminated string value.
593  *
594  * @param ops The `as_operations` to append the operation to.
595  * @param name The name of the bin to perform the operation on.
596  * @param value The value to be used in the operation. Must last for the lifetime of the operations.
597  *
598  * @return true on success. Otherwise an error occurred.
599  *
600  * @relates as_operations
601  * @ingroup as_operations_object
602  */
603 static inline bool as_operations_add_append_str(as_operations * ops, const as_bin_name name, const char * value)
604 {
605  return as_operations_add_append_strp(ops, name, value, false);
606 }
607 
608 /**
609  * Add a `AS_OPERATOR_APPEND` bin operation with a raw bytes value.
610  *
611  * @param ops The `as_operations` to append the operation to.
612  * @param name The name of the bin to perform the operation on.
613  * @param value The value to be used in the operation.
614  * @param size The size of the value.
615  * @param free If true, then the value will be freed when the operations is destroyed.
616  *
617  * @return true on success. Otherwise an error occurred.
618  *
619  * @relates as_operations
620  * @ingroup as_operations_object
621  */
622 bool as_operations_add_append_rawp(as_operations * ops, const as_bin_name name, const uint8_t * value, uint32_t size, bool free);
623 
624 /**
625  * Add a `AS_OPERATOR_APPEND` bin operation with a raw bytes value.
626  *
627  * @param ops The `as_operations` to append the operation to.
628  * @param name The name of the bin to perform the operation on.
629  * @param value The value to be used in the operation. Must last for the lifetime of the operations.
630  * @param size The size of the value.
631  *
632  * @return true on success. Otherwise an error occurred.
633  *
634  * @relates as_operations
635  * @ingroup as_operations_object
636  */
637 static inline bool as_operations_add_append_raw(as_operations * ops, const as_bin_name name, const uint8_t * value, uint32_t size)
638 {
639  return as_operations_add_append_rawp(ops, name, value, size, false);
640 }
641 
642 /**
643  * Add a `AS_OPERATOR_TOUCH` record operation.
644  *
645  * @param ops The `as_operations` to append the operation to.
646  *
647  * @return true on success. Otherwise an error occurred.
648  *
649  * @relates as_operations
650  * @ingroup as_operations_object
651  */
bool as_operations_add_append_rawp(as_operations *ops, const as_bin_name name, const uint8_t *value, uint32_t size, bool free)
bool as_operations_add_write_int64(as_operations *ops, const as_bin_name name, int64_t value)
static bool as_operations_add_prepend_raw(as_operations *ops, const as_bin_name name, const uint8_t *value, uint32_t size)
uint16_t size
as_operations * as_operations_new(uint16_t nops)
void as_operations_destroy(as_operations *ops)
as_binop * entries
as_operations * as_operations_init(as_operations *ops, uint16_t nops)
bool as_operations_add_incr(as_operations *ops, const as_bin_name name, int64_t value)
static bool as_operations_add_write_str(as_operations *ops, const as_bin_name name, const char *value)
static bool as_operations_add_prepend_str(as_operations *ops, const as_bin_name name, const char *value)
bool as_operations_add_prepend_rawp(as_operations *ops, const as_bin_name name, const uint8_t *value, uint32_t size, bool free)
Definition: as_bin.h:71
static bool as_operations_add_append_raw(as_operations *ops, const as_bin_name name, const uint8_t *value, uint32_t size)
as_operator
Definition: as_operations.h:30
uint16_t capacity
as_bin bin
Definition: as_operations.h:81
bool as_operations_add_write(as_operations *ops, const as_bin_name name, as_bin_value *value)
as_binops binops
static bool as_operations_add_write_raw(as_operations *ops, const as_bin_name name, const uint8_t *value, uint32_t size)
bool as_operations_add_write_strp(as_operations *ops, const as_bin_name name, const char *value, bool free)
bool as_operations_add_write_rawp(as_operations *ops, const as_bin_name name, const uint8_t *value, uint32_t size, bool free)
char as_bin_name[AS_BIN_NAME_MAX_SIZE]
Definition: as_bin.h:47
bool as_operations_add_read(as_operations *ops, const as_bin_name name)
bool as_operations_add_append_strp(as_operations *ops, const as_bin_name name, const char *value, bool free)
bool as_operations_add_touch(as_operations *ops)
as_operator op
Definition: as_operations.h:76
bool as_operations_add_prepend_strp(as_operations *ops, const as_bin_name name, const char *value, bool free)
static bool as_operations_add_append_str(as_operations *ops, const as_bin_name name, const char *value)