Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
aerospike_scan.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
* @defgroup scan_operations Scan Operations
21
* @ingroup client_operations
22
*
23
* Aerospike Scan Operations provide the ability to scan all record of a
24
* namespace and set in an Aerospike database.
25
*
26
* ## Usage
27
*
28
* Before you can execute a scan, you first need to define a scan using
29
* as_scan. See as_scan for details on defining scans.
30
*
31
* Once you have a scan defined, then you can execute the scan
32
* using either:
33
*
34
* - aerospike_scan_foreach() — Execute a scan on the database, then process
35
* the results.
36
* - aerospike_scan_background() — Send a scan to the database, and not wait
37
* for completed. The scan is given an id, which can be used to query the
38
* scan status.
39
*
40
* When aerospike_scan_foreach() is executed, it will process the results
41
* and create records on the stack. Because the records are on the stack,
42
* they will only be available within the context of the callback function.
43
*
44
* When aerospike_scan_background() is executed, the client will not wait for
45
* results from the database. Instead, the client will be given a scan_id,
46
* which can be used to query the scan status on the database via
47
* aerospike_scan_info().
48
*
49
* ## Walk-through
50
*
51
* First, we build a scan using as_scan. The scan will be on the "test"
52
* namespace and "demo" set. We will select only bins "a" and "b" to be returned
53
* for each record.
54
*
55
* ~~~~~~~~~~{.c}
56
* as_scan scan;
57
* as_scan_init(&scan, "test", "demo");
58
*
59
* as_scan_select_inita(&scan, 2);
60
* as_scan_select(&scan, "a");
61
* as_scan_select(&scan, "B");
62
* ~~~~~~~~~~
63
*
64
* Now that we have a scan defined, we want to execute it using
65
* aerospike_scan_foreach().
66
*
67
* ~~~~~~~~~~{.c}
68
* if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
69
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
70
* }
71
* ~~~~~~~~~~
72
*
73
* The callback provided to the function above is implemented as:
74
*
75
* ~~~~~~~~~~{.c}
76
* bool callback(const as_val * val, void * udata) {
77
* as_record * rec = as_record_fromval(val);
78
* if ( !rec ) return false;
79
* fprintf("record contains %d bins", as_record_numbins(rec));
80
* return true;
81
* }
82
* ~~~~~~~~~~
83
*
84
* An as_scan is simply a scan definition, so it does not contain any state,
85
* allowing it to be reused for multiple scan operations.
86
*
87
* When you are finished with the scan, you should destroy the resources
88
* allocated to it:
89
*
90
* ~~~~~~~~~~{.c}
91
* as_scan_destroy(&scan);
92
* ~~~~~~~~~~
93
*/
94
95
#include <
aerospike/aerospike.h
>
96
#include <
aerospike/as_error.h
>
97
#include <
aerospike/as_policy.h
>
98
#include <
aerospike/as_scan.h
>
99
#include <
aerospike/as_status.h
>
100
#include <
aerospike/as_val.h
>
101
102
#ifdef __cplusplus
103
extern
"C"
{
104
#endif
105
106
/******************************************************************************
107
* TYPES
108
*****************************************************************************/
109
110
/**
111
* This callback will be called for each value or record returned from a scan.
112
* Multiple threads will likely be calling this callback in parallel. Therefore,
113
* your callback implementation should be thread safe.
114
*
115
* The following functions accept the callback:
116
* - aerospike_scan_foreach()
117
* - aerospike_scan_node()
118
*
119
* ~~~~~~~~~~{.c}
120
* bool my_callback(const as_val * val, void * udata) {
121
* return true;
122
* }
123
* ~~~~~~~~~~
124
*
125
* @param val The value received from the query.
126
* @param udata User-data provided to the calling function.
127
*
128
* @return `true` to continue to the next value. Otherwise, iteration will end.
129
*
130
* @ingroup scan_operations
131
*/
132
typedef
bool (*
aerospike_scan_foreach_callback
)(
const
as_val
* val,
void
* udata);
133
134
/******************************************************************************
135
* FUNCTIONS
136
*****************************************************************************/
137
138
/**
139
* Scan the records in the specified namespace and set in the cluster.
140
*
141
* Scan will be run in the background by a thread on client side.
142
* No callback will be called in this case.
143
*
144
* ~~~~~~~~~~{.c}
145
* as_scan scan;
146
* as_scan_init(&scan, "test", "demo");
147
*
148
* uint64_t scanid = 0;
149
*
150
* if ( aerospike_scan_background(&as, &err, NULL, &scan, &scanid) != AEROSPIKE_OK ) {
151
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
152
* }
153
* else {
154
* printf("Running background scan job: %ll", scanid);
155
* }
156
*
157
* as_scan_destroy(&scan);
158
* ~~~~~~~~~~
159
*
160
* The scanid can be used to query the status of the scan running in the
161
* database via aerospike_scan_info().
162
*
163
* @param as The aerospike instance to use for this operation.
164
* @param err The as_error to be populated if an error occurs.
165
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
166
* @param scan The scan to execute against the cluster.
167
* @param scan_id The id for the scan job, which can be used for querying the status of the scan.
168
*
169
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
170
*
171
* @ingroup scan_operations
172
*/
173
as_status
aerospike_scan_background
(
174
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
175
const
as_scan
* scan, uint64_t * scan_id
176
);
177
178
/**
179
* Wait for a background scan to be completed by servers.
180
*
181
* ~~~~~~~~~~{.c}
182
* uint64_t scan_id = 1234;
183
* aerospike_scan_wait(&as, &err, NULL, scan_id, 0);
184
* ~~~~~~~~~~
185
*
186
* @param as The aerospike instance to use for this operation.
187
* @param err The as_error to be populated if an error occurs.
188
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
189
* @param scan_id The id for the scan job.
190
* @param interval_ms The polling interval in milliseconds. If zero, 1000 ms is used.
191
*
192
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
193
*/
194
as_status
aerospike_scan_wait
(
195
aerospike
* as,
as_error
* err,
const
as_policy_info
* policy,
196
uint64_t scan_id, uint32_t interval_ms
197
);
198
199
/**
200
* Check the progress of a background scan running on the database. The status
201
* of the scan running on the datatabse will be populated into an as_scan_info.
202
*
203
* ~~~~~~~~~~{.c}
204
* uint64_t scan_id = 1234;
205
* as_scan_info scan_info;
206
*
207
* if ( aerospike_scan_info(&as, &err, NULL, &scan, scan_id, &scan_info) != AEROSPIKE_OK ) {
208
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
209
* }
210
* else {
211
* printf("Scan id=%ll, status=%d percent=%d", scan_id, scan_info.status, scan_info.progress_pct);
212
* }
213
* ~~~~~~~~~~
214
*
215
*
216
* @param as The aerospike instance to use for this operation.
217
* @param err The as_error to be populated if an error occurs.
218
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
219
* @param scan_id The id for the scan job to check the status of.
220
* @param info Information about this scan, to be populated by this operation.
221
*
222
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
223
*
224
* @ingroup scan_operations
225
*/
226
as_status
aerospike_scan_info
(
227
aerospike
* as,
as_error
* err,
const
as_policy_info
* policy,
228
uint64_t scan_id,
as_scan_info
* info
229
);
230
231
/**
232
* Scan the records in the specified namespace and set in the cluster.
233
*
234
* Call the callback function for each record scanned. When all records have
235
* been scanned, then callback will be called with a NULL value for the record.
236
*
237
* Multiple threads will likely be calling the callback in parallel. Therefore,
238
* your callback implementation should be thread safe.
239
*
240
* ~~~~~~~~~~{.c}
241
* as_scan scan;
242
* as_scan_init(&scan, "test", "demo");
243
*
244
* if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
245
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
246
* }
247
*
248
* as_scan_destroy(&scan);
249
* ~~~~~~~~~~
250
*
251
*
252
* @param as The aerospike instance to use for this operation.
253
* @param err The as_error to be populated if an error occurs.
254
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
255
* @param scan The scan to execute against the cluster.
256
* @param callback The function to be called for each record scanned.
257
* @param udata User-data to be passed to the callback.
258
*
259
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
260
*
261
* @ingroup scan_operations
262
*/
263
as_status
aerospike_scan_foreach
(
264
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
265
const
as_scan
* scan,
266
aerospike_scan_foreach_callback
callback,
void
* udata
267
);
268
269
/**
270
* Scan the records in the specified namespace and set for a single node.
271
*
272
* The callback function will be called for each record scanned. When all records have
273
* been scanned, then callback will be called with a NULL value for the record.
274
*
275
* ~~~~~~~~~~{.c}
276
* char* node_names = NULL;
277
* int n_nodes = 0;
278
* as_cluster_get_node_names(as->cluster, &n_nodes, &node_names);
279
*
280
* if (n_nodes <= 0)
281
* return <error>;
282
*
283
* as_scan scan;
284
* as_scan_init(&scan, "test", "demo");
285
*
286
* if (aerospike_scan_node(&as, &err, NULL, &scan, node_names[0], callback, NULL) != AEROSPIKE_OK ) {
287
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
288
* }
289
*
290
* free(node_names);
291
* as_scan_destroy(&scan);
292
* ~~~~~~~~~~
293
*
294
* @param as The aerospike instance to use for this operation.
295
* @param err The as_error to be populated if an error occurs.
296
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
297
* @param scan The scan to execute against the cluster.
298
* @param node_name The node name to scan.
299
* @param callback The function to be called for each record scanned.
300
* @param udata User-data to be passed to the callback.
301
*
302
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
303
*
304
* @ingroup scan_operations
305
*/
306
as_status
aerospike_scan_node
(
307
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
308
const
as_scan
* scan,
const
char
* node_name,
309
aerospike_scan_foreach_callback
callback,
void
* udata
310
);
311
312
#ifdef __cplusplus
313
}
// end extern "C"
314
#endif