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