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