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