All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
src/include/aerospike/aerospike_lstack.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 /**
24  * @defgroup ldt_operations Large Data Type Operations (3.0 only)
25  * @ingroup client_operations
26  *
27  * The ldt_operations module provides API to manipulate
28  * Large Data Types. Currently supported types include:
29  * - lstack = large stack
30  * - lset = large set
31  *
32  * Forthcoming API:
33  * - llist = large list
34  * - lmap = large map
35  *
36  */
37 
38 #pragma once
39 
40 #include <aerospike/aerospike.h>
41 #include <aerospike/as_error.h>
42 #include <aerospike/as_ldt.h>
43 #include <aerospike/as_list.h>
44 #include <aerospike/as_operations.h>
45 #include <aerospike/as_policy.h>
46 #include <aerospike/as_status.h>
47 #include <aerospike/as_key.h>
48 #include <aerospike/as_val.h>
49 
50 /******************************************************************************
51  * FUNCTIONS
52  *****************************************************************************/
53 
54 /**
55  * Push a value onto the lstack.
56  *
57  * ~~~~~~~~~~{.c}
58  * as_key key;
59  * as_key_init(&key, "myns", "myset", "mykey");
60  *
61  * as_ldt stack;
62  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
63  *
64  * as_integer ival;
65  * as_integer_init(&ival, 123);
66  *
67  * if ( aerospike_lstack_push(&as, &err, NULL, &key, &stack, (as_val *) &ival) != AEROSPIKE_OK ) {
68  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
69  * }
70  * ~~~~~~~~~~
71  *
72  * @param as The aerospike instance to use for this operation.
73  * @param err The as_error to be populated if an error occurs.
74  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
75  * @param key The key of the record.
76  * @param ldt The ldt bin to push values to.
77  * @param val The value to push on to the lstack.
78  *
79  * @return AEROSPIKE_OK if successful. Otherwise an error.
80  *
81  * @ingroup ldt_operations
82  */
84  aerospike * as, as_error * err, const as_policy_apply * policy,
85  const as_key * key, const as_ldt * ldt, const as_val * val);
86 
87 
88 /**
89  * Push a value onto the lstack.
90  *
91  * ~~~~~~~~~~{.c}
92  * as_key key;
93  * as_key_init(&key, "myns", "myset", "mykey");
94  *
95  * as_ldt stack;
96  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
97  *
98  * as_arraylist vals;
99  * as_arraylist_inita(&vals, 2);
100  * as_string s;
101  * as_string_init(s,"a string",false);
102  * as_arraylist_append_string(&vals, s);
103  * as_arraylist_append_int64(&vals, 35);
104  *
105  * if ( aerospike_lstack_push_all(&as, &err, NULL, &key, &stack, (as_val *) &ival) != AEROSPIKE_OK ) {
106  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
107  * }
108  * ~~~~~~~~~~
109  *
110  * @param as The aerospike instance to use for this operation.
111  * @param err The as_error to be populated if an error occurs.
112  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
113  * @param key The key of the record.
114  * @param ldt The ldt bin to push values to.
115  * @param vals The list of values to push on to the lstack. list[0] is the first to push on the stack.
116  * list[n] is top of the stack.
117  *
118  * @return AEROSPIKE_OK if successful. Otherwise an error.
119  *
120  * @ingroup ldt_operations
121  */
123  aerospike * as, as_error * err, const as_policy_apply * policy,
124  const as_key * key, const as_ldt * ldt, const as_list * vals);
125 
126 /**
127  * Look up an lstack, then peek to get the top n values from the stack.
128  *
129  * ~~~~~~~~~~{.c}
130  * as_key key;
131  * as_key_init(&key, "myns", "myset", "mykey");
132  *
133  * as_ldt stack;
134  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
135  *
136  * uint32_t peek_count = 3;
137  *
138  * as_arraylist list = as_arraylist_init(&list, peek_count, 0);
139  *
140  * if ( aerospike_lstack_peek(&as, &err, NULL, &key, &stack, peek_count, (as_list *) &list) != AEROSPIKE_OK ) {
141  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
142  * }
143  * else {
144  * // process the returned stack elements
145  * as_arraylist_destroy(list);
146  * }
147  * ~~~~~~~~~~
148  *
149  * @param as The aerospike instance to use for this operation.
150  * @param err The as_error to be populated if an error occurs.
151  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
152  * @param key The key of the record.
153  * @param ldt The stack bin to peek values from. If not a stack bin, will return error.
154  * @param n The number of elements to peek from the lstack.
155  * @param list Pointer to a list of elements peeked from the lstack.
156  * Pointer should be NULL passed in.
157  * If stack_size shorter than n, only stack_size is returned.
158  *
159  * @return AEROSPIKE_OK if successful. Otherwise an error.
160  *
161  * @ingroup ldt_operations
162  */
163 
165  aerospike * as, as_error * err, const as_policy_apply * policy,
166  const as_key * key, const as_ldt * ldt, uint32_t peek_count,
167  as_list ** elements );
168 
169 /**
170  * Look up a record by key, then peek into a stack bin, and do UDF post processing
171  * to filter for only the desired values.
172  *
173  * ~~~~~~~~~~{.c}
174  * as_key key;
175  * as_key_init(&key, "myns", "myset", "mykey");
176  *
177  * as_ldt stack;
178  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
179  *
180  * uint32_t peek_count = 3;
181  *
182  * as_arraylist list = as_arraylist_init(&list, peek_count, 0);
183  *
184  * if ( aerospike_lstack_peek_with_filter(&as, &err, NULL, &key, &stack, peek_count,
185  * "myfilter", NULL, (as_list *) &list) != AEROSPIKE_OK ) {
186  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
187  * }
188  * else {
189  * // process the returned stack elements
190  * as_arraylist_destroy(list);
191  * }
192  * ~~~~~~~~~~
193  *
194  * @param as The aerospike instance to use for this operation.
195  * @param err The as_error to be populated if an error occurs.
196  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
197  * @param key The key of the record.
198  * @param ldt The stack bin to peek values from. If not a stack bin, will return error.
199  * @param n The number of elements to peek from the lstack.
200  * @param filter The name of the User-Defined-Function to use as a stack element filter.
201  * @param fargs The list of parameters to the User-Defined-Function filter.
202  * @param list Pointer to list of elements peeked from the lstack.
203  * Pointer should be initialized to NULL when passed in;
204  *
205  * @return AEROSPIKE_OK if successful. Otherwise an error.
206  *
207  * @ingroup ldt_operations
208  */
210  aerospike * as, as_error * err, const as_policy_apply * policy,
211  const as_key * key, const as_ldt * ldt, uint32_t peek_count,
212  const as_udf_function_name filter, const as_list *filter_args,
213  as_list ** elements );
214 
215 /**
216  * Find how many elements are on the lstack
217  *
218  * ~~~~~~~~~~{.c}
219  * as_key key;
220  * as_key_init(&key, "myns", "myset", "mykey");
221  *
222  * as_ldt stack;
223  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
224  * uint32_t stack_size = 0;
225  *
226  * if ( aerospike_lstack_size(&as, &err, NULL, &key, &stack, &stack_size) != AEROSPIKE_OK ) {
227  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
228  * }
229  * ~~~~~~~~~~
230  *
231  * @param as The aerospike instance to use for this operation.
232  * @param err The as_error to be populated if an error occurs.
233  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
234  * @param key The key of the record.
235  * @param ldt The stack bin to peek values from. If not a stack bin, will return error.
236  * @param n Return the number of elements on the lstack.
237  *
238  * @return AEROSPIKE_OK if successful. Otherwise an error.
239  *
240  * @ingroup ldt_operations
241  */
243  aerospike * as, as_error * err, const as_policy_apply * policy,
244  const as_key * key, const as_ldt * ldt,
245  uint32_t *n
246  );
247 
248 /**
249  * Change an lstack storage capacity (in number of elements)
250  *
251  * ~~~~~~~~~~{.c}
252  * as_key key;
253  * as_key_init(&key, "myns", "myset", "mykey");
254  *
255  * as_ldt stack;
256  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
257  * uint32_t cap_elements = 0;
258  *
259  * if ( aerospike_lstack_set_capacity(&as, &err, NULL, &key, &stack, cap_elements) != AEROSPIKE_OK ) {
260  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
261  * }
262  * ~~~~~~~~~~
263  *
264  * @param as The aerospike instance to use for this operation.
265  * @param err The as_error to be populated if an error occurs.
266  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
267  * @param key The key of the record.
268  * @param ldt The stack bin to peek values from. If not a stack bin, will return error.
269  * @param n The number of elements cap for the lstack.
270  *
271  * @return AEROSPIKE_OK if successful. Otherwise an error.
272  *
273  * @ingroup ldt_operations
274  */
276  aerospike * as, as_error * err, const as_policy_apply * policy,
277  const as_key * key, const as_ldt * ldt, uint32_t n
278  );
279 
280 /**
281  * Get an lstack's storage capacity (in number of elements)
282  *
283  * ~~~~~~~~~~{.c}
284  * as_key key;
285  * as_key_init(&key, "myns", "myset", "mykey");
286  *
287  * as_ldt stack;
288  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
289  * uint32_t cap_elements = 0;
290  *
291  * if ( aerospike_lstack_get_capacity(&as, &err, NULL, &key, &stack, &cap_elements) != AEROSPIKE_OK ) {
292  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
293  * }
294  * ~~~~~~~~~~
295  *
296  * @param as The aerospike instance to use for this operation.
297  * @param err The as_error to be populated if an error occurs.
298  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
299  * @param key The key of the record.
300  * @param ldt The stack bin to peek values from. If not a stack bin, will return error.
301  * @param n The number of elements cap for the lstack.
302  *
303  * @return AEROSPIKE_OK if successful. Otherwise an error.
304  *
305  * @ingroup ldt_operations
306  */
308  aerospike * as, as_error * err, const as_policy_apply * policy,
309  const as_key * key, const as_ldt * ldt,
310  uint32_t *n
311  );
312 
313 
314 /**
315  * Destroys an existing lstack
316  *
317  * ~~~~~~~~~~{.c}
318  * as_key key;
319  * as_key_init(&key, "myns", "myset", "mykey");
320  *
321  * as_ldt stack;
322  * as_ldt_init(&stack, "mystack", AS_LDT_LSTACK, NULL);
323  * uint32_t cap_elements = 0;
324  *
325  * if ( aerospike_lstack_destroy(&as, &err, NULL, &key, &stack) != AEROSPIKE_OK ) {
326  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
327  * }
328  * ~~~~~~~~~~
329  *
330  * @param as The aerospike instance to use for this operation.
331  * @param err The as_error to be populated if an error occurs.
332  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
333  * @param key The key of the record.
334  * @param ldt The stack bin to peek values from. If not a stack bin, will return error.
335  *
336  * @return AEROSPIKE_OK if successful. Otherwise an error.
337  *
338  * @ingroup ldt_operations
339  */
340 
342  aerospike * as, as_error * err, const as_policy_apply * policy,
343  const as_key * key, const as_ldt * ldt
344  );
as_status aerospike_lstack_size(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t *n)
as_status aerospike_lstack_filter(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t peek_count, const as_udf_function_name filter, const as_list *filter_args, as_list **elements)
as_status aerospike_lstack_set_capacity(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t n)
as_status aerospike_lstack_destroy(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt)
as_status aerospike_lstack_peek(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t peek_count, as_list **elements)
as_status aerospike_lstack_get_capacity(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t *n)
as_status aerospike_lstack_push(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *val)
char as_udf_function_name[AS_UDF_FUNCTION_MAX_SIZE]
as_status aerospike_lstack_push_all(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_list *vals)