Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
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 (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
>
38
#include <
aerospike/as_operations.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
*/
82
as_status
aerospike_lstack_push
(
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
*/
121
as_status
aerospike_lstack_push_all
(
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
163
as_status
aerospike_lstack_peek
(
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
*/
208
as_status
aerospike_lstack_filter
(
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
241
as_status
aerospike_lstack_destroy
(
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
*/
273
as_status
aerospike_lstack_size
(
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
*/
306
as_status
aerospike_lstack_set_capacity
(
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
*/
338
as_status
aerospike_lstack_get_capacity
(
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
*/
371
as_status
aerospike_lstack_ldt_exists
(
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