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