Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
aerospike.h
Go to the documentation of this file.
1
/*
2
* Copyright 2008-2017 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
* @mainpage Aerospike C Client
21
*
22
* @section intro_sec Introduction
23
*
24
* The Aerospike C client allows you to build C/C++ applications to store and retrieve data from the
25
* Aerospike cluster. The C client is a smart client that periodically pings nodes for cluster
26
* status and manages interactions with the cluster. The following functionality is supported.
27
*
28
* - Database commands
29
* - Key/Value
30
* - Map/List collections
31
* - Batch read
32
* - Scan
33
* - Secondary index query
34
* - User defined Lua functions
35
* - Both synchronous and asynchronous command models
36
* - Asynchronous model supports the following event frameworks.
37
* - libev
38
* - libevent
39
* - libuv
40
* - Thread safe API
41
* - Shared memory cluster tend state for multi-process applications
42
* - TLS secure sockets
43
*
44
* See <a href="modules.html">Modules</a> for an API overview.
45
*
46
* See <a href="http://www.aerospike.com/docs/client/c">Developer Guide</a> for installation
47
* instructions and example code.
48
*/
49
50
/**
51
* @defgroup client_objects Client Objects
52
*/
53
54
/**
55
* @defgroup client_operations Client Operations
56
*
57
* Client operations require an initialized @ref aerospike client.
58
*/
59
60
/**
61
* @defgroup aerospike_t Client Types
62
*/
63
64
/**
65
* @defgroup client_utilities Utilities
66
* @{
67
* @defgroup stringmap_t StringMap
68
* @}
69
*/
70
71
#include <
aerospike/as_error.h
>
72
#include <
aerospike/as_config.h
>
73
#include <
aerospike/as_log.h
>
74
#include <
aerospike/as_status.h
>
75
#include <stdbool.h>
76
77
#ifdef __cplusplus
78
extern
"C"
{
79
#endif
80
81
/******************************************************************************
82
* TYPES
83
*****************************************************************************/
84
85
/**
86
* @private
87
* Forward declaration of a cluster object.
88
*/
89
struct
as_cluster_s;
90
91
/**
92
* An instance of @ref aerospike is required to connect to and execute
93
* operations against an Aerospike Database cluster.
94
*
95
* ## Configuration
96
*
97
* An initialized client configuration is required to initialize a
98
* @ref aerospike client. See as_config for details on configuration options.
99
*
100
* At a minimum, a configuration needs to be initialized and have at least
101
* one host defined:
102
*
103
* ~~~~~~~~~~{.c}
104
* as_config config;
105
* as_config_init(&config);
106
* as_config_add_host(&config, "127.0.0.1", 3000);
107
* ~~~~~~~~~~
108
*
109
* Once connected to a host in the cluster, then client will gather information
110
* about the cluster, including all other nodes in the cluster. So, all that
111
* is needed is a single valid host. Multiple hosts can still be provided in
112
* case the first host is not currently active.
113
*
114
* ## Initialization
115
*
116
* An initialized @ref aerospike object is required to connect to the
117
* database. Initialization requires a configuration to bind to the client
118
* instance.
119
*
120
* The @ref aerospike object can be initialized via either:
121
*
122
* - aerospike_init() — Initialize a stack allocated @ref aerospike.
123
* - aerospike_new() — Create and initialize a heap allocated @ref aerospike.
124
*
125
* Both initialization functions require a configuration. Once initialized, the ownership
126
* of the as_config instance fields are transferred to @ref aerospike. The user should never
127
* call as_config_destroy() directly.
128
*
129
* The following uses a stack allocated @ref aerospike and initializes it
130
* with aerospike_init():
131
*
132
* ~~~~~~~~~~{.c}
133
* aerospike as;
134
* aerospike_init(&as, &config);
135
* ~~~~~~~~~~
136
*
137
* ## Connecting
138
*
139
* An application can connect to the database with an initialized
140
* @ref aerospike. The client will be connected if `aerospike_connect()` completes
141
* successfully:
142
*
143
* ~~~~~~~~~~{.c}
144
* if (aerospike_connect(&as, &err) != AEROSPIKE_OK) {
145
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
146
* }
147
* ~~~~~~~~~~
148
*
149
* The `err` parameter will be populated if an error while attempting to
150
* connect to the database. See as_error, for more information on error
151
* handling.
152
*
153
* An aerospike object internally keeps cluster state and maintains connection pools to the cluster.
154
* The same aerospike object should be reused by the application for database operations
155
* to a given cluster.
156
*
157
* If the application requires connecting to multiple Aerospike clusters, the application must
158
* create multiple aerospike objects, each connecting to a different cluster.
159
*
160
* ## Disconnecting
161
*
162
* When the connection to the database is not longer required, then the
163
* connection to the cluster can be closed via `aerospike_close()`:
164
*
165
* ~~~~~~~~~~{.c}
166
* aerospike_close(&as, &err);
167
* ~~~~~~~~~~
168
*
169
* ## Destruction
170
*
171
* When the client is not longer required, the client and its resources should
172
* be releases via `aerospike_destroy()`:
173
*
174
* ~~~~~~~~~~{.c}
175
* aerospike_destroy(&as);
176
* ~~~~~~~~~~
177
*
178
* @ingroup client_objects
179
*/
180
typedef
struct
aerospike_s {
181
182
/**
183
* @private
184
* If true, then aerospike_destroy() will free this instance.
185
*/
186
bool
_free;
187
188
/**
189
* @private
190
* Cluster state.
191
*/
192
struct
as_cluster_s *
cluster
;
193
194
/**
195
* Client configuration.
196
*/
197
as_config
config
;
198
199
}
aerospike
;
200
201
/******************************************************************************
202
* FUNCTIONS
203
*****************************************************************************/
204
205
/**
206
* Initialize a stack allocated aerospike instance.
207
*
208
* The config parameter can be an instance of `as_config` or `NULL`. If `NULL`,
209
* then the default configuration will be used.
210
*
211
* Ownership of the as_config instance fields are transferred to @ref aerospike.
212
* The user should never call as_config_destroy() directly.
213
*
214
* ~~~~~~~~~~{.c}
215
* aerospike as;
216
* aerospike_init(&as, &config);
217
* ~~~~~~~~~~
218
*
219
* Once you are finished using the instance, then you should destroy it via the
220
* `aerospike_destroy()` function.
221
*
222
* @param as The aerospike instance to initialize.
223
* @param config The configuration to use for the instance.
224
*
225
* @returns the initialized aerospike instance
226
*
227
* @see config for information on configuring the client.
228
*
229
* @relates aerospike
230
*/
231
aerospike
*
232
aerospike_init
(
aerospike
* as,
as_config
* config);
233
234
/**
235
* Creates a new heap allocated aerospike instance.
236
*
237
* Ownership of the as_config instance fields are transferred to @ref aerospike.
238
* The user should never call as_config_destroy() directly.
239
*
240
* ~~~~~~~~~~{.c}
241
* aerospike* as = aerospike_new(&config);
242
* ~~~~~~~~~~
243
*
244
* Once you are finished using the instance, then you should destroy it via the
245
* `aerospike_destroy()` function.
246
*
247
* @param config The configuration to use for the instance.
248
*
249
* @returns a new aerospike instance
250
*
251
* @see config for information on configuring the client.
252
*
253
* @relates aerospike
254
*/
255
aerospike
*
256
aerospike_new
(
as_config
* config);
257
258
/**
259
* Initialize global lua configuration.
260
*
261
* @param config The lua configuration to use for all cluster instances.
262
*/
263
void
264
aerospike_init_lua
(
as_config_lua
* config);
265
266
/**
267
* Destroy the aerospike instance and associated resources.
268
*
269
* ~~~~~~~~~~{.c}
270
* aerospike_destroy(&as);
271
* ~~~~~~~~~~
272
*
273
* @param as The aerospike instance to destroy
274
*
275
* @relates aerospike
276
*/
277
void
278
aerospike_destroy
(
aerospike
* as);
279
280
/**
281
* Connect an aerospike instance to the cluster.
282
*
283
* ~~~~~~~~~~{.c}
284
* aerospike_connect(&as, &err);
285
* ~~~~~~~~~~
286
*
287
* Once you are finished using the connection, then you must close it via
288
* the `aerospike_close()` function.
289
*
290
* If connect fails, then you do not need to call `aerospike_close()`.
291
*
292
* @param as The aerospike instance to connect to a cluster.
293
* @param err If an error occurs, the err will be populated.
294
*
295
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
296
*
297
* @relates aerospike
298
*/
299
as_status
300
aerospike_connect
(
aerospike
* as,
as_error
* err);
301
302
/**
303
* Close connections to the cluster.
304
*
305
* ~~~~~~~~~~{.c}
306
* aerospike_close(&as, &err);
307
* ~~~~~~~~~~
308
*
309
* @param as The aerospike instance to disconnect from a cluster.
310
* @param err If an error occurs, the err will be populated.
311
*
312
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
313
*
314
* @relates aerospike
315
*/
316
as_status
317
aerospike_close
(
aerospike
* as,
as_error
* err);
318
319
/**
320
* Is cluster connected to any server nodes.
321
*
322
* ~~~~~~~~~~{.c}
323
* bool connected = aerospike_cluster_is_connected(&as);
324
* ~~~~~~~~~~
325
*
326
* @param as The aerospike instance to check.
327
*
328
* @returns true when cluster is connected.
329
*
330
* @relates aerospike
331
*/
332
bool
333
aerospike_cluster_is_connected
(
aerospike
* as);
334
335
/**
336
* Do all server nodes in the cluster support async pipelining.
337
*
338
* @param as The aerospike instance to check.
339
*
340
* @returns true when all server nodes support pipelining.
341
*
342
* @relates aerospike
343
*/
344
bool
345
aerospike_has_pipelining
(
aerospike
* as);
346
347
/**
348
* Should stop socket operation if interrupted by a signal. Default is false which means
349
* the socket operation will be retried until timeout.
350
*
351
* @relates aerospike
352
*/
353
void
354
aerospike_stop_on_interrupt
(
bool
stop);
355
356
/**
357
* Remove records in specified namespace/set efficiently. This method is many orders of magnitude
358
* faster than deleting records one at a time. Works with Aerospike Server versions >= 3.12.
359
*
360
* This asynchronous server call may return before the truncation is complete. The user can still
361
* write new records after the server returns because new records will have last update times
362
* greater than the truncate cutoff (set at the time of truncate call).
363
*
364
* @param as Aerospike instance.
365
* @param err If an error occurs, the err will be populated.
366
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
367
* @param ns Required namespace.
368
* @param set Optional set name. Pass in NULL to delete all sets in namespace.
369
* @param before_nanos Optionally delete records before record last update time.
370
* Units are in nanoseconds since unix epoch (1970-01-01).
371
* If specified, value must be before the current time.
372
* Pass in 0 to delete all records in namespace/set regardless of last update time.
373
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
374
*
375
* @relates aerospike
376
*/
377
as_status
378
aerospike_truncate
(
aerospike
* as,
as_error
* err,
as_policy_info
* policy,
const
char
*
ns
,
const
char
* set, uint64_t before_nanos);
379
380
/**
381
* Refresh the current TLS configuration by reloading its certificate, key, and blacklist files.
382
*
383
* @param as Aerospike instance whose TLS configuration to refresh.
384
* @param err If an error occurs, this will be populated.
385
*
386
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
387
*
388
* @relates aerospike
389
*/
390
as_status
391
aerospike_reload_tls_config
(
aerospike
* as,
as_error
* err);
392
393
#ifdef __cplusplus
394
}
// end extern "C"
395
#endif