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-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  * 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  * @deprecated LDT functionality has been deprecated.
61  *
62  * @param as The aerospike instance to use for this operation.
63  * @param err The as_error to be populated if an error occurs.
64  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
65  * @param key The key of the record.
66  * @param ldt The ldt bin to insert values to.
67  * @param mkey The map-key.
68  * @param mval The map-value associated with mkey.
69  *
70  * @return AEROSPIKE_OK if successful. Otherwise an error.
71  *
72  * @ingroup ldt_operations
73  */
75  aerospike * as, as_error * err, const as_policy_apply * policy,
76  const as_key * key, const as_ldt * ldt,
77  const as_val * mkey, const as_val * mval
78  );
79 
80 /**
81  * Add multiple entries into the lmap.
82  *
83  * ~~~~~~~~~~{.c}
84  * as_key key;
85  * as_key_init(&key, "myns", "myset", "mykey");
86  *
87  * as_ldt lmap;
88  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
89  *
90  *
91  * as_arraylist vals;
92  * as_arraylist_inita(&vals, 2);
93  * as_string s;
94  * as_string_init(s,"a string",false);
95  * as_arraylist_append_string(&vals, s);
96  * as_arraylist_append_int64(&vals, 35);
97  *
98  * if ( aerospike_lmap_put_all(&as, &err, NULL, &key, &lmap, (const as_map *)vals) != AEROSPIKE_OK ) {
99  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
100  * }
101  *
102  * ~~~~~~~~~~
103  *
104  * @deprecated LDT functionality has been deprecated.
105  *
106  * @param as The aerospike instance to use for this operation.
107  * @param err The as_error to be populated if an error occurs.
108  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
109  * @param key The key of the record.
110  * @param ldt The ldt bin to insert values to.
111  * @param vals A map containing the entries to add to the lmap.
112  *
113  * @return AEROSPIKE_OK if successful. Otherwise an error.
114  *
115  * @ingroup ldt_operations
116  */
118  aerospike * as, as_error * err, const as_policy_apply * policy,
119  const as_key * key, const as_ldt * ldt, const as_map * vals
120  );
121 
122 /**
123  * Get the value of an entry in the Lmap, using the given map-key
124  *
125  * ~~~~~~~~~~{.c}
126  * as_key key;
127  * as_key_init(&key, "myns", "myset", "mykey");
128  *
129  * as_ldt lmap;
130  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
131  *
132  * as_integer ival;
133  * as_integer_init(&ival, 123);
134  *
135  * boolean exists = false;
136  *
137  * if ( aerospike_lmap_get(&as, &err, NULL, &key, &lmap, &ikey, &p_val) != AEROSPIKE_OK ) {
138  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
139  * }
140  * else {
141  * // do logic because element exists
142  * }
143  * ~~~~~~~~~~
144  *
145  * @deprecated LDT functionality has been deprecated.
146  *
147  * @param as The aerospike instance to use for this operation.
148  * @param err The as_error to be populated if an error occurs.
149  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
150  * @param key The key of the record.
151  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
152  * @param mkey The map key.
153  * @param mval Returned map value.
154  *
155  * @return AEROSPIKE_OK if successful. Otherwise an error.
156  *
157  * @ingroup ldt_operations
158  */
159 
161  aerospike * as, as_error * err, const as_policy_apply * policy,
162  const as_key * key, const as_ldt * ldt, const as_val * mkey,
163  as_val ** mval
164  );
165 
166 /**
167  * Get all the entries in an lmap
168  *
169  * ~~~~~~~~~~{.c}
170  * as_key key;
171  * as_key_init(&key, "myns", "myset", "mykey");
172  *
173  * as_ldt lmap;
174  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
175  *
176  * as_map *p_map = NULL;
177  *
178  * if ( aerospike_lmap_get_all(&as, &err, NULL, &key, &lmap, &p_map) != AEROSPIKE_OK ) {
179  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
180  * }
181  * else {
182  * // do logic because element exists
183  * }
184  * ~~~~~~~~~~
185  *
186  * @deprecated LDT functionality has been deprecated.
187  *
188  * @param as The aerospike instance to use for this operation.
189  * @param err The as_error to be populated if an error occurs.
190  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
191  * @param key The key of the record.
192  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
193  * @param elements Returned pointer to the map of entries.
194  *
195  * @return AEROSPIKE_OK if successful. Otherwise an error.
196  *
197  * @ingroup ldt_operations
198  */
199 
201  aerospike * as, as_error * err, const as_policy_apply * policy,
202  const as_key * key, const as_ldt * ldt,
203  as_map ** elements
204  );
205 
206 /**
207  * Given an lmap bin, scan through all entries in the map, and apply the
208  * given filter function. If no filter function is specified, all values
209  * in the lmap will be returned.
210  *
211  * ~~~~~~~~~~{.c}
212  * as_key key;
213  * as_key_init(&key, "myns", "myset", "mykey");
214  *
215  * as_ldt lmap;
216  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
217  *
218  * as_map *p_map = NULL;
219  *
220  * if ( aerospike_lmap_filter(&as, &err, NULL, &key, &lmap,
221  * "counter_filter", NULL, (as_map *) &p_map) != AEROSPIKE_OK ) {
222  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
223  * }
224  * else {
225  * // process the returned elements
226  * as_map_destroy(p_map);
227  * }
228  * ~~~~~~~~~~
229  *
230  * @deprecated LDT functionality has been deprecated.
231  *
232  * @param as The aerospike instance to use for this operation.
233  * @param err The as_error to be populated if an error occurs.
234  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
235  * @param key The key of the record.
236  * @param ldt The lmap bin to operate on. If not an lmap bin, will return error.
237  * @param filter The name of the User-Defined-Function to use as a read-filter.
238  * The UDF should either return the entry, or nil, if filtered out.
239  * @param filter_args The list of parameters passed in to the User-Defined-Function filter.
240  * @param elements The pointer to a map of entries returned from the function. Pointer should
241  * be NULL passed in.
242  *
243  * @return AEROSPIKE_OK if successful. Otherwise an error.
244  *
245  * @ingroup ldt_operations
246  */
248  aerospike * as, as_error * err, const as_policy_apply * policy,
249  const as_key * key, const as_ldt * ldt,
250  const as_udf_function_name filter, const as_list *filter_args,
251  as_map ** elements
252  );
253 
254 /**
255  * Look up a lmap and find how many elements it contains
256  *
257  * ~~~~~~~~~~{.c}
258  * as_key key;
259  * as_key_init(&key, "myns", "myset", "mykey");
260  *
261  * as_ldt lmap;
262  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
263  * uint32_t lmap_size = 0;
264  *
265  * if ( aerospike_lmap_size(&as, &err, NULL, &key, &lmap, &lmap_size) != AEROSPIKE_OK ) {
266  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
267  * }
268  * ~~~~~~~~~~
269  *
270  * @deprecated LDT functionality has been deprecated.
271  *
272  * @param as The aerospike instance to use for this operation.
273  * @param err The as_error to be populated if an error occurs.
274  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
275  * @param key The key of the record.
276  * @param ldt The lmap to operate on. If not an lmap bin, will return error.
277  * @param n Return the number of elements in the lmap.
278  *
279  * @return AEROSPIKE_OK if successful. Otherwise an error.
280  *
281  * @ingroup ldt_operations
282  */
284  aerospike * as, as_error * err, const as_policy_apply * policy,
285  const as_key * key, const as_ldt * ldt,
286  uint32_t *n
287  );
288 
289 /**
290  * Delete the given value from the lmap
291  *
292  * ~~~~~~~~~~{.c}
293  * as_key key;
294  * as_key_init(&key, "myns", "myset", "mykey");
295  *
296  * as_ldt lmap;
297  * as_ldt_init(&lmap, "lmap", AS_LDT_LMAP, NULL);
298  *
299  * as_integer ival;
300  * as_integer_init(&ival, 123);
301  *
302  * if ( aerospike_lmap_remove(&as, &err, NULL, &key, &lmap, (const as_val*)&ikey) != 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 lmap bin to delete from. If not an lmap bin, will return error.
314  * @param mkey The key to delete from the set.
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, const as_val *mkey
323  );
324 
325 /**
326  * Destroy the lmap bin
327  *
328  * ~~~~~~~~~~{.c}
329  * as_key key;
330  * as_key_init(&key, "myns", "myset", "mykey");
331  *
332  * as_ldt lmap;
333  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
334  *
335  * if ( aerospike_lmap_destroy(&as, &err, NULL, &key, &lmap) != AEROSPIKE_OK ) {
336  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
337  * }
338  * ~~~~~~~~~~
339  *
340  * @deprecated LDT functionality has been deprecated.
341  *
342  * @param as The aerospike instance to use for this operation.
343  * @param err The as_error to be populated if an error occurs.
344  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
345  * @param key The key of the record.
346  * @param ldt The lmap bin to destroy. If not an lmap bin, will return error.
347  *
348  * @return AEROSPIKE_OK if successful. Otherwise an error.
349  *
350  * @ingroup ldt_operations
351  */
353  aerospike * as, as_error * err, const as_policy_apply * policy,
354  const as_key * key, const as_ldt * ldt
355  );
356 
357 /**
358  * Change an LDT storage capacity (in number of elements)
359  *
360  * ~~~~~~~~~~{.c}
361  * as_key key;
362  * as_key_init(&key, "myns", "myset", "mykey");
363  *
364  * as_ldt lmap;
365  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
366  * uint32_t ldt_capacity = 0;
367  *
368  * if ( aerospike_lmap_set_capacity(&as, &err, NULL, &key, &lmap, ldt_capacity) != AEROSPIKE_OK ) {
369  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
370  * }
371  * ~~~~~~~~~~
372  *
373  * @deprecated LDT functionality has been deprecated.
374  *
375  * @param as The aerospike instance to use for this operation.
376  * @param err The as_error to be populated if an error occurs.
377  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
378  * @param key The key of the record.
379  * @param ldt The LDT to check
380  * @param ldt_capacity The new capacity for this LDT, in terms of elements, not bytes
381  *
382  * @return AEROSPIKE_OK if successful. Otherwise an error.
383  *
384  * @ingroup ldt_operations
385  */
387  aerospike * as, as_error * err, const as_policy_apply * policy,
388  const as_key * key, const as_ldt * ldt, uint32_t ldt_capacity
389  );
390 
391 /**
392  * Get an LDTs storage capacity (in number of elements)
393  *
394  * ~~~~~~~~~~{.c}
395  * as_key key;
396  * as_key_init(&key, "myns", "myset", "mykey");
397  *
398  * as_ldt lmap;
399  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
400  * uint32_t ldt_capacity = 0;
401  *
402  * if ( aerospike_lmap_get_capacity(&as, &err, NULL, &key, &lmap, &ldt_capacity) != AEROSPIKE_OK ) {
403  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
404  * }
405  * ~~~~~~~~~~
406  *
407  * @deprecated LDT functionality has been deprecated.
408  *
409  * @param as The aerospike instance to use for this operation.
410  * @param err The as_error to be populated if an error occurs.
411  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
412  * @param key The key of the record.
413  * @param ldt The LDT bin to operate on
414  * @param ldt_capacity The LDT Capacity, in terms of elements, not bytes.
415  *
416  * @return AEROSPIKE_OK if successful. Otherwise an error.
417  *
418  * @ingroup ldt_operations
419  */
421  aerospike * as, as_error * err, const as_policy_apply * policy,
422  const as_key * key, const as_ldt * ldt,
423  uint32_t *ldt_capacity
424  );
425 
426 /**
427  * Check to see if an LDT object exists in this record bin.
428  *
429  * ~~~~~~~~~~{.c}
430  * as_key key;
431  * as_key_init(&key, "myns", "myset", "mykey");
432  *
433  * as_ldt lmap;
434  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
435  * uint32_t ldt_exists = 0;
436  *
437  * if ( aerospike_lmap_ldt_exists(&as, &err, NULL, &key, &lmap, &ldt_exists) != AEROSPIKE_OK ) {
438  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
439  * }
440  * ~~~~~~~~~~
441  *
442  * @deprecated LDT functionality has been deprecated.
443  *
444  * @param as The aerospike instance to use for this operation.
445  * @param err The as_error to be populated if an error occurs.
446  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
447  * @param key The key of the record.
448  * @param ldt The LDT to operate on. If not an LMAP bin, will return error.
449  * @param ldt_exists Ptr to as_boolean: Set to TRUE if ldt exists, otherwise false.
450  *
451  * @return AEROSPIKE_OK if successful. Otherwise an error.
452  *
453  * @ingroup ldt_operations
454  */
456  aerospike * as, as_error * err, const as_policy_apply * policy,
457  const as_key * key, const as_ldt * ldt,
458  as_boolean *ldt_exists
459  );
460 
461 
462 #ifdef __cplusplus
463 } // end extern "C"
464 #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)