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