All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike_lmap.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2015 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  * Functionality related to Large Map Data Type
21  */
22 
23 #include <aerospike/aerospike.h>
24 #include <aerospike/as_error.h>
25 #include <aerospike/as_ldt.h>
26 #include <aerospike/as_list.h>
28 #include <aerospike/as_policy.h>
29 #include <aerospike/as_status.h>
30 #include <aerospike/as_key.h>
31 #include <aerospike/as_val.h>
32 #include <aerospike/as_boolean.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /******************************************************************************
39  * FUNCTIONS
40  *****************************************************************************/
41 
42 /**
43  * Add a value into the lmap.
44  *
45  * ~~~~~~~~~~{.c}
46  * as_key key;
47  * as_key_init(&key, "myns", "myset", "mykey");
48  *
49  * as_ldt lmap;
50  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
51  *
52  * as_integer ival;
53  * as_integer_init(&ival, 123);
54  *
55  * if ( aerospike_lmap_put(&as, &err, NULL, &key, &lmap, (const as_val *) &ival, (as_val *) &ival) != AEROSPIKE_OK ) {
56  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
57  * }
58  * ~~~~~~~~~~
59  *
60  * @param as The aerospike instance to use for this operation.
61  * @param err The as_error to be populated if an error occurs.
62  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
63  * @param key The key of the record.
64  * @param ldt The ldt bin to insert values to.
65  * @param mkey The map-key.
66  * @param mval The map-value associated with mkey.
67  *
68  * @return AEROSPIKE_OK if successful. Otherwise an error.
69  *
70  * @ingroup ldt_operations
71  */
73  aerospike * as, as_error * err, const as_policy_apply * policy,
74  const as_key * key, const as_ldt * ldt,
75  const as_val * mkey, const as_val * mval
76  );
77 
78 /**
79  * Add multiple entries into the lmap.
80  *
81  * ~~~~~~~~~~{.c}
82  * as_key key;
83  * as_key_init(&key, "myns", "myset", "mykey");
84  *
85  * as_ldt lmap;
86  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
87  *
88  *
89  * as_arraylist vals;
90  * as_arraylist_inita(&vals, 2);
91  * as_string s;
92  * as_string_init(s,"a string",false);
93  * as_arraylist_append_string(&vals, s);
94  * as_arraylist_append_int64(&vals, 35);
95  *
96  * if ( aerospike_lmap_put_all(&as, &err, NULL, &key, &lmap, (const as_map *)vals) != AEROSPIKE_OK ) {
97  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
98  * }
99  *
100  * ~~~~~~~~~~
101  *
102  * @param as The aerospike instance to use for this operation.
103  * @param err The as_error to be populated if an error occurs.
104  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
105  * @param key The key of the record.
106  * @param ldt The ldt bin to insert values to.
107  * @param vals A map containing the entries to add to the lmap.
108  *
109  * @return AEROSPIKE_OK if successful. Otherwise an error.
110  *
111  * @ingroup ldt_operations
112  */
114  aerospike * as, as_error * err, const as_policy_apply * policy,
115  const as_key * key, const as_ldt * ldt, const as_map * vals
116  );
117 
118 /**
119  * Get the value of an entry in the Lmap, using the given map-key
120  *
121  * ~~~~~~~~~~{.c}
122  * as_key key;
123  * as_key_init(&key, "myns", "myset", "mykey");
124  *
125  * as_ldt lmap;
126  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
127  *
128  * as_integer ival;
129  * as_integer_init(&ival, 123);
130  *
131  * boolean exists = false;
132  *
133  * if ( aerospike_lmap_get(&as, &err, NULL, &key, &lmap, &ikey, &p_val) != AEROSPIKE_OK ) {
134  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
135  * }
136  * else {
137  * // do logic because element exists
138  * }
139  * ~~~~~~~~~~
140  *
141  * @param as The aerospike instance to use for this operation.
142  * @param err The as_error to be populated if an error occurs.
143  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
144  * @param key The key of the record.
145  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
146  * @param mkey The map key.
147  * @param mval Returned map value.
148  *
149  * @return AEROSPIKE_OK if successful. Otherwise an error.
150  *
151  * @ingroup ldt_operations
152  */
153 
155  aerospike * as, as_error * err, const as_policy_apply * policy,
156  const as_key * key, const as_ldt * ldt, const as_val * mkey,
157  as_val ** mval
158  );
159 
160 /**
161  * Get all the entries in an lmap
162  *
163  * ~~~~~~~~~~{.c}
164  * as_key key;
165  * as_key_init(&key, "myns", "myset", "mykey");
166  *
167  * as_ldt lmap;
168  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
169  *
170  * as_map *p_map = NULL;
171  *
172  * if ( aerospike_lmap_get_all(&as, &err, NULL, &key, &lmap, &p_map) != AEROSPIKE_OK ) {
173  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
174  * }
175  * else {
176  * // do logic because element exists
177  * }
178  * ~~~~~~~~~~
179  *
180  * @param as The aerospike instance to use for this operation.
181  * @param err The as_error to be populated if an error occurs.
182  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
183  * @param key The key of the record.
184  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
185  * @param elements Returned pointer to the map of entries.
186  *
187  * @return AEROSPIKE_OK if successful. Otherwise an error.
188  *
189  * @ingroup ldt_operations
190  */
191 
193  aerospike * as, as_error * err, const as_policy_apply * policy,
194  const as_key * key, const as_ldt * ldt,
195  as_map ** elements
196  );
197 
198 /**
199  * Given an lmap bin, scan through all entries in the map, and apply the
200  * given filter function. If no filter function is specified, all values
201  * in the lmap will be returned.
202  *
203  * ~~~~~~~~~~{.c}
204  * as_key key;
205  * as_key_init(&key, "myns", "myset", "mykey");
206  *
207  * as_ldt lmap;
208  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
209  *
210  * as_map *p_map = NULL;
211  *
212  * if ( aerospike_lmap_filter(&as, &err, NULL, &key, &lmap,
213  * "counter_filter", NULL, (as_map *) &p_map) != AEROSPIKE_OK ) {
214  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
215  * }
216  * else {
217  * // process the returned elements
218  * as_map_destroy(p_map);
219  * }
220  * ~~~~~~~~~~
221  *
222  * @param as The aerospike instance to use for this operation.
223  * @param err The as_error to be populated if an error occurs.
224  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
225  * @param key The key of the record.
226  * @param ldt The lmap bin to operate on. If not an lmap bin, will return error.
227  * @param filter The name of the User-Defined-Function to use as a read-filter.
228  * The UDF should either return the entry, or nil, if filtered out.
229  * @param filter_args The list of parameters passed in to the User-Defined-Function filter.
230  * @param elements The pointer to a map of entries returned from the function. Pointer should
231  * be NULL passed in.
232  *
233  * @return AEROSPIKE_OK if successful. Otherwise an error.
234  *
235  * @ingroup ldt_operations
236  */
238  aerospike * as, as_error * err, const as_policy_apply * policy,
239  const as_key * key, const as_ldt * ldt,
240  const as_udf_function_name filter, const as_list *filter_args,
241  as_map ** elements
242  );
243 
244 /**
245  * Look up a lmap and find how many elements it contains
246  *
247  * ~~~~~~~~~~{.c}
248  * as_key key;
249  * as_key_init(&key, "myns", "myset", "mykey");
250  *
251  * as_ldt lmap;
252  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
253  * uint32_t lmap_size = 0;
254  *
255  * if ( aerospike_lmap_size(&as, &err, NULL, &key, &lmap, &lmap_size) != AEROSPIKE_OK ) {
256  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
257  * }
258  * ~~~~~~~~~~
259  *
260  * @param as The aerospike instance to use for this operation.
261  * @param err The as_error to be populated if an error occurs.
262  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
263  * @param key The key of the record.
264  * @param ldt The lmap to operate on. If not an lmap bin, will return error.
265  * @param n Return the number of elements in the lmap.
266  *
267  * @return AEROSPIKE_OK if successful. Otherwise an error.
268  *
269  * @ingroup ldt_operations
270  */
272  aerospike * as, as_error * err, const as_policy_apply * policy,
273  const as_key * key, const as_ldt * ldt,
274  uint32_t *n
275  );
276 
277 /**
278  * Delete the given value from the lmap
279  *
280  * ~~~~~~~~~~{.c}
281  * as_key key;
282  * as_key_init(&key, "myns", "myset", "mykey");
283  *
284  * as_ldt lmap;
285  * as_ldt_init(&lmap, "lmap", AS_LDT_LMAP, NULL);
286  *
287  * as_integer ival;
288  * as_integer_init(&ival, 123);
289  *
290  * if ( aerospike_lmap_remove(&as, &err, NULL, &key, &lmap, (const as_val*)&ikey) != 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 lmap bin to delete from. If not an lmap bin, will return error.
300  * @param mkey The key to delete from the set.
301  *
302  * @return AEROSPIKE_OK if successful. Otherwise an error.
303  *
304  * @ingroup ldt_operations
305  */
307  aerospike * as, as_error * err, const as_policy_apply * policy,
308  const as_key * key, const as_ldt * ldt, const as_val *mkey
309  );
310 
311 /**
312  * Destroy the lmap bin
313  *
314  * ~~~~~~~~~~{.c}
315  * as_key key;
316  * as_key_init(&key, "myns", "myset", "mykey");
317  *
318  * as_ldt lmap;
319  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
320  *
321  * if ( aerospike_lmap_destroy(&as, &err, NULL, &key, &lmap) != AEROSPIKE_OK ) {
322  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
323  * }
324  * ~~~~~~~~~~
325  *
326  * @param as The aerospike instance to use for this operation.
327  * @param err The as_error to be populated if an error occurs.
328  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
329  * @param key The key of the record.
330  * @param ldt The lmap bin to destroy. If not an lmap bin, will return error.
331  *
332  * @return AEROSPIKE_OK if successful. Otherwise an error.
333  *
334  * @ingroup ldt_operations
335  */
337  aerospike * as, as_error * err, const as_policy_apply * policy,
338  const as_key * key, const as_ldt * ldt
339  );
340 
341 /**
342  * Change an LDT storage capacity (in number of elements)
343  *
344  * ~~~~~~~~~~{.c}
345  * as_key key;
346  * as_key_init(&key, "myns", "myset", "mykey");
347  *
348  * as_ldt lmap;
349  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
350  * uint32_t ldt_capacity = 0;
351  *
352  * if ( aerospike_lmap_set_capacity(&as, &err, NULL, &key, &lmap, ldt_capacity) != AEROSPIKE_OK ) {
353  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
354  * }
355  * ~~~~~~~~~~
356  *
357  * @param as The aerospike instance to use for this operation.
358  * @param err The as_error to be populated if an error occurs.
359  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
360  * @param key The key of the record.
361  * @param ldt The LDT to check
362  * @param ldt_capacity The new capacity for this LDT, in terms of elements, not bytes
363  *
364  * @return AEROSPIKE_OK if successful. Otherwise an error.
365  *
366  * @ingroup ldt_operations
367  */
369  aerospike * as, as_error * err, const as_policy_apply * policy,
370  const as_key * key, const as_ldt * ldt, uint32_t ldt_capacity
371  );
372 
373 /**
374  * Get an LDTs storage capacity (in number of elements)
375  *
376  * ~~~~~~~~~~{.c}
377  * as_key key;
378  * as_key_init(&key, "myns", "myset", "mykey");
379  *
380  * as_ldt lmap;
381  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
382  * uint32_t ldt_capacity = 0;
383  *
384  * if ( aerospike_lmap_get_capacity(&as, &err, NULL, &key, &lmap, &ldt_capacity) != AEROSPIKE_OK ) {
385  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
386  * }
387  * ~~~~~~~~~~
388  *
389  * @param as The aerospike instance to use for this operation.
390  * @param err The as_error to be populated if an error occurs.
391  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
392  * @param key The key of the record.
393  * @param ldt The LDT bin to operate on
394  * @param ldt_capacity The LDT Capacity, in terms of elements, not bytes.
395  *
396  * @return AEROSPIKE_OK if successful. Otherwise an error.
397  *
398  * @ingroup ldt_operations
399  */
401  aerospike * as, as_error * err, const as_policy_apply * policy,
402  const as_key * key, const as_ldt * ldt,
403  uint32_t *ldt_capacity
404  );
405 
406 /**
407  * Check to see if an LDT object exists in this record bin.
408  *
409  * ~~~~~~~~~~{.c}
410  * as_key key;
411  * as_key_init(&key, "myns", "myset", "mykey");
412  *
413  * as_ldt lmap;
414  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
415  * uint32_t ldt_exists = 0;
416  *
417  * if ( aerospike_lmap_ldt_exists(&as, &err, NULL, &key, &lmap, &ldt_exists) != AEROSPIKE_OK ) {
418  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
419  * }
420  * ~~~~~~~~~~
421  *
422  * @param as The aerospike instance to use for this operation.
423  * @param err The as_error to be populated if an error occurs.
424  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
425  * @param key The key of the record.
426  * @param ldt The LDT to operate on. If not an LMAP bin, will return error.
427  * @param ldt_exists Ptr to as_boolean: Set to TRUE if ldt exists, otherwise false.
428  *
429  * @return AEROSPIKE_OK if successful. Otherwise an error.
430  *
431  * @ingroup ldt_operations
432  */
434  aerospike * as, as_error * err, const as_policy_apply * policy,
435  const as_key * key, const as_ldt * ldt,
436  as_boolean *ldt_exists
437  );
438 
439 
440 #ifdef __cplusplus
441 } // end extern "C"
442 #endif
as_status aerospike_lmap_get(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *mkey, as_val **mval)
as_status aerospike_lmap_filter(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_udf_function_name filter, const as_list *filter_args, as_map **elements)
Definition: as_map.h:61
as_status
Definition: as_status.h:30
as_status aerospike_lmap_get_all(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, as_map **elements)
as_status aerospike_lmap_put(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *mkey, const as_val *mval)
Definition: as_val.h:57
char as_udf_function_name[AS_UDF_FUNCTION_MAX_SIZE]
Definition: as_udf.h:82
as_status aerospike_lmap_put_all(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_map *vals)
as_status aerospike_lmap_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 aerospike_lmap_set_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 aerospike_lmap_destroy(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt)
as_status aerospike_lmap_ldt_exists(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, as_boolean *ldt_exists)
Definition: as_ldt.h:52
as_status aerospike_lmap_remove(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, const as_val *mkey)
Definition: as_key.h:199
as_status aerospike_lmap_size(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const as_ldt *ldt, uint32_t *n)