Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
target
Linux-x86_64
include
aerospike
target/Linux-x86_64/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
*/
83
as_status
aerospike_lstack_push
(
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
*/
122
as_status
aerospike_lstack_push_all
(
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
164
as_status
aerospike_lstack_peek
(
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
*/
209
as_status
aerospike_lstack_filter
(
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
*/
242
as_status
aerospike_lstack_size
(
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
*/
275
as_status
aerospike_lstack_set_capacity
(
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
*/
307
as_status
aerospike_lstack_get_capacity
(
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
341
as_status
aerospike_lstack_destroy
(
342
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
343
const
as_key
*
key
,
const
as_ldt
* ldt
344
);