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-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
>
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
/******************************************************************************
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
*/
78
as_status
aerospike_lstack_push
(
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
*/
117
as_status
aerospike_lstack_push_all
(
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
159
as_status
aerospike_lstack_peek
(
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
*/
204
as_status
aerospike_lstack_filter
(
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
237
as_status
aerospike_lstack_destroy
(
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
*/
269
as_status
aerospike_lstack_size
(
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
*/
302
as_status
aerospike_lstack_set_capacity
(
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
*/
334
as_status
aerospike_lstack_get_capacity
(
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
*/
367
as_status
aerospike_lstack_ldt_exists
(
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