All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
target/Linux-x86_64/include/aerospike/as_scan.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 #pragma once
24 #pragma GCC diagnostic ignored "-Waddress"
25 
26 #include <aerospike/as_bin.h>
27 #include <aerospike/as_key.h>
28 #include <aerospike/as_udf.h>
29 
30 /******************************************************************************
31  * MACROS
32  *****************************************************************************/
33 
34 /**
35  * Default value for as_scan.priority
36  */
37 #define AS_SCAN_PRIORITY_DEFAULT AS_SCAN_PRIORITY_AUTO
38 
39 /**
40  * Default value for as_scan.percent
41  */
42 #define AS_SCAN_PERCENT_DEFAULT 100
43 
44 /**
45  * Default value for as_scan.no_bins
46  */
47 #define AS_SCAN_NOBINS_DEFAULT false
48 
49 /**
50  * Default value for as_scan.concurrent
51  */
52 #define AS_SCAN_CONCURRENT_DEFAULT false
53 
54 /******************************************************************************
55  * TYPES
56  *****************************************************************************/
57 
58 /**
59  * Priority levels for a scan operation.
60  */
61 typedef enum as_scan_priority_e {
62 
63  /**
64  * The cluster will auto adjust the scan priority.
65  */
67 
68  /**
69  * Low priority scan.
70  */
72 
73  /**
74  * Medium priority scan.
75  */
77 
78  /**
79  * High priority scan.
80  */
82 
84 
85 /**
86  * The status of a particular background scan.
87  */
88 typedef enum as_scan_status_e {
89 
90  /**
91  * The scan status is undefined.
92  * This is likely due to the status not being properly checked.
93  */
95 
96  /**
97  * The scan is currently running.
98  */
100 
101  /**
102  * The scan was aborted. Due to failure or the user.
103  */
105 
106  /**
107  * The scan completed successfully.
108  */
110 
112 
113 /**
114  * Information about a particular background scan.
115  *
116  * @ingroup as_scan_object
117  */
118 typedef struct as_scan_info_s {
119 
120  /**
121  * Status of the scan.
122  */
123  as_scan_status status;
124 
125  /**
126  * Progress estimate for the scan, as percentage.
127  */
128  uint32_t progress_pct;
129 
130  /**
131  * How many records have been scanned.
132  */
133  uint32_t records_scanned;
134 
135 } as_scan_info;
136 
137 /**
138  * Sequence of bins which should be selected during a scan.
139  *
140  * Entries can either be initialized on the stack or on the heap.
141  *
142  * Initialization should be performed via a query object, using:
143  * - as_scan_select_init()
144  * - as_scan_select_inita()
145  */
146 typedef struct as_scan_bins_s {
147 
148  /**
149  * @private
150  * If true, then as_scan_destroy() will free this instance.
151  */
152  bool _free;
153 
154  /**
155  * Number of entries allocated
156  */
157  uint16_t capacity;
158 
159  /**
160  * Number of entries used
161  */
162  uint16_t size;
163 
164  /**
165  * Sequence of entries
166  */
167  as_bin_name * entries;
168 
169 } as_scan_bins;
170 
171 /**
172  * In order to execute a scan using the Scan API, an as_scan object
173  * must be initialized and populated.
174  *
175  * ## Initialization
176  *
177  * Before using an as_scan, it must be initialized via either:
178  * - as_scan_init()
179  * - as_scan_new()
180  *
181  * as_scan_init() should be used on a stack allocated as_scan. It will
182  * initialize the as_scan with the given namespace and set. On success,
183  * it will return a pointer to the initialized as_scan. Otherwise, NULL
184  * is returned.
185  *
186  * ~~~~~~~~~~{.c}
187  * as_scan scan;
188  * as_scan_init(&scan, "namespace", "set");
189  * ~~~~~~~~~~
190  *
191  * as_scan_new() should be used to allocate and initialize a heap allocated
192  * as_scan. It will allocate the as_scan, then initialized it with the
193  * given namespace and set. On success, it will return a pointer to the
194  * initialized as_scan. Otherwise, NULL is returned.
195  *
196  * ~~~~~~~~~~{.c}
197  * as_scan * scan = as_scan_new("namespace", "set");
198  * ~~~~~~~~~~
199  *
200  * ## Destruction
201  *
202  * When you are finished with the as_scan, you can destroy it and associated
203  * resources:
204  *
205  * ~~~~~~~~~~{.c}
206  * as_scan_destroy(scan);
207  * ~~~~~~~~~~
208  *
209  * ## Usage
210  *
211  * An initialized as_query can be populated with additional fields.
212  *
213  * ### Selecting Bins
214  *
215  * as_scan_select() is used to specify the bins to be selected by the scan.
216  * If a scan specifies bins to be selected, then only those bins will be
217  * returned. If no bins are selected, then all bins will be returned.
218  *
219  * ~~~~~~~~~~{.c}
220  * as_scan_select(query, "bin1");
221  * as_scan_select(query, "bin2");
222  * ~~~~~~~~~~
223  *
224  * Before adding bins to select, the select structure must be initialized via
225  * either:
226  * - as_scan_select_inita() - Initializes the structure on the stack.
227  * - as_scan_select_init() - Initializes the structure on the heap.
228  *
229  * Both functions are given the number of bins to be selected.
230  *
231  * A complete example using as_scan_select_inita()
232  *
233  * ~~~~~~~~~~{.c}
234  * as_scan_select_inita(query, 2);
235  * as_scan_select(query, "bin1");
236  * as_scan_select(query, "bin2");
237  * ~~~~~~~~~~
238  *
239  * ### Returning only meta data
240  *
241  * A scan can return only record meta data, and exclude bins.
242  *
243  * ~~~~~~~~~~{.c}
244  * as_scan_set_nobins(scan, true);
245  * ~~~~~~~~~~
246  *
247  * ### Scan nodes in parallel
248  *
249  * A scan can be made to scan all the nodes in parallel
250  *
251  * ~~~~~~~~~~{.c}
252  * as_scan_set_concurrent(scan, true);
253  * ~~~~~~~~~~
254  *
255  * ### Scan a Percentage of Records
256  *
257  * A scan can define the percentage of record in the cluster to be scaned.
258  *
259  * ~~~~~~~~~~{.c}
260  * as_scan_set_percent(scan, 100);
261  * ~~~~~~~~~~
262  *
263  * ### Scan a Priority
264  *
265  * To set the priority of the scan, the set as_scan.priority.
266  *
267  * The priority of a scan can be defined as either:
268  * - `AS_SCAN_PRIORITY_AUTO`
269  * - `AS_SCAN_PRIORITY_LOW`
270  * - `AS_SCAN_PRIORITY_MEDIUM`
271  * - `AS_SCAN_PRIORITY_HIGH`
272  *
273  * ~~~~~~~~~~{.c}
274  * as_scan_set_priority(scan, AS_SCAN_PRIORITY_LOW);
275  * ~~~~~~~~~~
276  *
277  * ### Applying a UDF to each Record Scanned
278  *
279  * A UDF can be applied to each record scanned.
280  *
281  * To define the UDF for the scan, use as_scan_apply_each().
282  *
283  * ~~~~~~~~~~{.c}
284  * as_scan_apply_each(scan, "udf_module", "udf_function", arglist);
285  * ~~~~~~~~~~
286  *
287  * @ingroup client_objects
288  */
289 typedef struct as_scan_s {
290 
291  /**
292  * @private
293  * If true, then as_scan_destroy() will free this instance.
294  */
295  bool _free;
296 
297  /**
298  * Priority of scan.
299  *
300  * Default value is AS_SCAN_PRIORITY_DEFAULT.
301  */
302  as_scan_priority priority;
303 
304  /**
305  * Percentage of the data to scan.
306  *
307  * Default value is AS_SCAN_PERCENT_DEFAULT.
308  */
309  uint8_t percent;
310 
311  /**
312  * Set to true if the scan should return only the metadata of the record.
313  *
314  * Default value is AS_SCAN_NOBINS_DEFAULT.
315  */
316  bool no_bins;
317 
318  /**
319  * Set to true if the scan should scan all the nodes in parallel
320  *
321  * Default value is AS_SCAN_CONCURRENT_DEFAULT.
322  */
323  bool concurrent;
324 
325  /**
326  * @memberof as_scan
327  * Namespace to be scanned.
328  *
329  * Should be initialized via either:
330  * - as_scan_init() - To initialize a stack allocated scan.
331  * - as_scan_new() - To heap allocate and initialize a scan.
332  *
333  */
335 
336  /**
337  * Set to be scanned.
338  *
339  * Should be initialized via either:
340  * - as_scan_init() - To initialize a stack allocated scan.
341  * - as_scan_new() - To heap allocate and initialize a scan.
342  *
343  */
344  as_set set;
345 
346  /**
347  * Name of bins to select.
348  *
349  * Use either of the following function to initialize:
350  * - as_scan_select_init() - To initialize on the heap.
351  * - as_scan_select_inita() - To initialize on the stack.
352  *
353  * Use as_scan_select() to populate.
354  */
355  as_scan_bins select;
356 
357  /**
358  * Apply the UDF for each record scanned on the server.
359  *
360  * Should be set via `as_scan_apply_each()`.
361  */
362  as_udf_call apply_each;
363 
364 } as_scan;
365 
366 /******************************************************************************
367  * INSTANCE FUNCTIONS
368  *****************************************************************************/
369 
370 /**
371  * Initializes a scan.
372  *
373  * ~~~~~~~~~~{.c}
374  * as_scan scan;
375  * as_scan_init(&scan, "test", "demo");
376  * ~~~~~~~~~~
377  *
378  * When you no longer require the scan, you should release the scan and
379  * related resources via `as_scan_destroy()`.
380  *
381  * @param scan The scan to initialize.
382  * @param ns The namespace to scan.
383  * @param set The set to scan.
384  *
385  * @returns On succes, the initialized scan. Otherwise NULL.
386  *
387  * @relates as_scan
388  * @ingroup as_scan_object
389  */
390 as_scan * as_scan_init(as_scan * scan, const as_namespace ns, const as_set set);
391 
392 /**
393  * Create and initializes a new scan on the heap.
394  *
395  * ~~~~~~~~~~{.c}
396  * as_scan * scan = as_scan_new("test","demo");
397  * ~~~~~~~~~~
398  *
399  * When you no longer require the scan, you should release the scan and
400  * related resources via `as_scan_destroy()`.
401  *
402  * @param ns The namespace to scan.
403  * @param set The set to scan.
404  *
405  * @returns On success, a new scan. Otherwise NULL.
406  *
407  * @relates as_scan
408  * @ingroup as_scan_object
409  */
410 as_scan * as_scan_new(const as_namespace ns, const as_set set);
411 
412 /**
413  * Releases all resources allocated to the scan.
414  *
415  * ~~~~~~~~~~{.c}
416  * as_scan_destroy(scan);
417  * ~~~~~~~~~~
418  *
419  * @relates as_scan
420  * @ingroup as_scan_object
421  */
422 void as_scan_destroy(as_scan * scan);
423 
424 /******************************************************************************
425  * SELECT FUNCTIONS
426  *****************************************************************************/
427 
428 /**
429  * Initializes `as_scan.select` with a capacity of `n` using `alloca`
430  *
431  * For heap allocation, use `as_scan_select_init()`.
432  *
433  * ~~~~~~~~~~{.c}
434  * as_scan_select_inita(&scan, 2);
435  * as_scan_select(&scan, "bin1");
436  * as_scan_select(&scan, "bin2");
437  * ~~~~~~~~~~
438  *
439  * @param __scan The scan to initialize.
440  * @param __n The number of bins to allocate.
441  *
442  * @ingroup as_scan_object
443  */
444 #define as_scan_select_inita(__scan, __n) \
445  if ( (__scan) != NULL && (__scan)->select.entries == NULL ) {\
446  (__scan)->select.entries = (as_bin_name *) alloca(__n * sizeof(as_bin_name));\
447  if ( (__scan)->select.entries ) { \
448  (__scan)->select._free = false;\
449  (__scan)->select.capacity = __n;\
450  (__scan)->select.size = 0;\
451  }\
452  }
453 
454 /**
455  * Initializes `as_scan.select` with a capacity of `n` using `malloc()`.
456  *
457  * For stack allocation, use `as_scan_select_inita()`.
458  *
459  * ~~~~~~~~~~{.c}
460  * as_scan_select_init(&scan, 2);
461  * as_scan_select(&scan, "bin1");
462  * as_scan_select(&scan, "bin2");
463  * ~~~~~~~~~~
464  *
465  * @param scan The scan to initialize.
466  * @param n The number of bins to allocate.
467  *
468  * @return On success, the initialized. Otherwise an error occurred.
469  *
470  * @relates as_scan
471  * @ingroup as_scan_object
472  */
473 bool as_scan_select_init(as_scan * scan, uint16_t n);
474 
475 /**
476  * Select bins to be projected from matching records.
477  *
478  * You have to ensure as_scan.select has sufficient capacity, prior to
479  * adding a bin. If capacity is insufficient then false is returned.
480  *
481  * ~~~~~~~~~~{.c}
482  * as_scan_select_init(&scan, 2);
483  * as_scan_select(&scan, "bin1");
484  * as_scan_select(&scan, "bin2");
485  * ~~~~~~~~~~
486  *
487  * @param scan The scan to modify.
488  * @param bin The name of the bin to select.
489  *
490  * @return On success, true. Otherwise an error occurred.
491  *
492  * @relates as_scan
493  * @ingroup as_scan_object
494  */
495 bool as_scan_select(as_scan * scan, const char * bin);
496 
497 /******************************************************************************
498  * MODIFIER FUNCTIONS
499  *****************************************************************************/
500 
501 /**
502  * The percentage of data to scan.
503  *
504  * ~~~~~~~~~~{.c}
505  * as_scan_set_percent(&q, 100);
506  * ~~~~~~~~~~
507  *
508  * @param scan The scan to set the priority on.
509  * @param percent The percent to scan.
510  *
511  * @return On success, true. Otherwise an error occurred.
512  *
513  * @relates as_scan
514  * @ingroup as_scan_object
515  */
516 bool as_scan_set_percent(as_scan * scan, uint8_t percent);
517 
518 /**
519  * Set the priority for the scan.
520  *
521  * ~~~~~~~~~~{.c}
522  * as_scan_set_priority(&q, AS_SCAN_PRIORITY_LOW);
523  * ~~~~~~~~~~
524  *
525  * @param scan The scan to set the priority on.
526  * @param priority The priority for the scan.
527  *
528  * @return On success, true. Otherwise an error occurred.
529  *
530  * @relates as_scan
531  * @ingroup as_scan_object
532  */
533 bool as_scan_set_priority(as_scan * scan, as_scan_priority priority);
534 
535 /**
536  * Do not return bins. This will only return the metadata for the records.
537  *
538  * ~~~~~~~~~~{.c}
539  * as_scan_set_nobins(&q, true);
540  * ~~~~~~~~~~
541  *
542  * @param scan The scan to set the priority on.
543  * @param nobins If true, then do not return bins.
544  *
545  * @return On success, true. Otherwise an error occurred.
546  *
547  * @relates as_scan
548  * @ingroup as_scan_object
549  */
550 bool as_scan_set_nobins(as_scan * scan, bool nobins);
551 
552 /**
553  * Scan all the nodes in prallel
554  *
555  * ~~~~~~~~~~{.c}
556  * as_scan_set_concurrent(&q, true);
557  * ~~~~~~~~~~
558  *
559  * @param scan The scan to set the concurrency on.
560  * @param concurrent If true, scan all the nodes in parallel
561  *
562  * @return On success, true. Otherwise an error occurred.
563  */
564 bool as_scan_set_concurrent(as_scan * scan, bool concurrent);
565 
566 /**
567  * Apply a UDF to each record scanned on the server.
568  *
569  * ~~~~~~~~~~{.c}
570  * as_arraylist arglist;
571  * as_arraylist_init(&arglist, 2, 0);
572  * as_arraylist_append_int64(&arglist, 1);
573  * as_arraylist_append_int64(&arglist, 2);
574  *
575  * as_scan_apply_each(&q, "module", "func", (as_list *) &arglist);
576  *
577  * as_arraylist_destroy(&arglist);
578  * ~~~~~~~~~~
579  *
580  * @param scan The scan to apply the UDF to.
581  * @param module The module containing the function to execute.
582  * @param function The function to execute.
583  * @param arglist The arguments for the function.
584  *
585  * @return On success, true. Otherwise an error occurred.
586  *
587  * @relates as_scan
588  * @ingroup as_scan_object
589  */
590 bool as_scan_apply_each(as_scan * scan, const char * module, const char * function, as_list * arglist);
bool as_scan_select(as_scan *scan, const char *bin)
as_scan * as_scan_init(as_scan *scan, const as_namespace ns, const as_set set)
bool as_scan_select_init(as_scan *scan, uint16_t n)
char as_namespace[AS_NAMESPACE_MAX_SIZE]
bool as_scan_set_percent(as_scan *scan, uint8_t percent)
void as_scan_destroy(as_scan *scan)
bool as_scan_set_concurrent(as_scan *scan, bool concurrent)
as_scan * as_scan_new(const as_namespace ns, const as_set set)
char as_set[AS_SET_MAX_SIZE]
bool as_scan_apply_each(as_scan *scan, const char *module, const char *function, as_list *arglist)
bool as_scan_set_nobins(as_scan *scan, bool nobins)
bool as_scan_set_priority(as_scan *scan, as_scan_priority priority)
char as_bin_name[AS_BIN_NAME_MAX_SIZE]