Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
target
Linux-x86_64
include
aerospike
target/Linux-x86_64/include/aerospike/aerospike.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
/**
24
* @mainpage Aerospike C Client
25
*
26
* @section intro_sec Introduction
27
*
28
* This package describes the Aerospike C Client API in detail.
29
* Click on "Modules" to see the API.
30
*
31
* For Overview and Developer Guide, please go to http://www.aerospike.com.
32
*
33
*
34
*/
35
36
/**
37
* @defgroup client_operations Client Operations
38
*
39
* Each of the client operations require an initialized @ref aerospike client.
40
*/
41
42
/**
43
* @defgroup client_objects Client Objects
44
*/
45
46
/**
47
* @defgroup aerospike_t Aerospike Types
48
*/
49
50
/**
51
* @defgroup client_utilities Client Utilities
52
* @{
53
* @defgroup stringmap_t
54
* @}
55
*/
56
57
#pragma once
58
59
#include <aerospike/as_error.h>
60
#include <aerospike/as_config.h>
61
#include <aerospike/as_log.h>
62
#include <aerospike/as_status.h>
63
#include <stdbool.h>
64
65
/******************************************************************************
66
* TYPES
67
*****************************************************************************/
68
69
/**
70
* @private
71
* Forward declaration of a cluster object.
72
*/
73
struct
cl_cluster_s
;
74
75
/**
76
* An instance of @ref aerospike is required to connect to and execute
77
* operations against an Aerospike Database cluster.
78
*
79
* ## Configuration
80
*
81
* An initialized client configuration is required to initialize a
82
* @ref aerospike client. See as_config for details on configuration options.
83
*
84
* At a minimum, a configuration needs to be initialized and have at least
85
* one host defined:
86
*
87
* ~~~~~~~~~~{.c}
88
* as_config config;
89
* as_config_init(&config);
90
* config.hosts[0] = { "127.0.0.1", 3000 };
91
* ~~~~~~~~~~
92
*
93
* A single host is used to specify a host in the database cluster to connect to.
94
* Once connected to a host in the cluster, then client will gather information
95
* about the cluster, including all the other nodes in the cluster. So, all that
96
* is needed is a single valid host, because once a single host is connected, the
97
* then no other hosts in the configuration will be processed.
98
*
99
* ## Initialization
100
*
101
* An initialized @ref aerospike object is required to connect to the
102
* database. Initialization requires a configuration, to bind to the client
103
* instance.
104
*
105
* The @ref aerospike object can be initialized via either:
106
*
107
* - aerospike_init() — Initialize a stack allocated @ref aerospike.
108
* - aerospike_new() — Create and initialize a heap allocated @ref aerospike.
109
*
110
* Both initialization functions require a configuration.
111
*
112
* The following uses a stack allocated @ref aerospike and initializes it
113
* with aerospike_init():
114
*
115
* ~~~~~~~~~~{.c}
116
* aerospike as;
117
* aerospike_init(&as, &config);
118
* ~~~~~~~~~~
119
*
120
* ## Connecting
121
*
122
* An application can connect to the database with an initialized
123
* @ref aerospike. At this point, the client has not connected. The
124
* client will be connected if `aerospike_connect()` completes
125
* successfully:
126
*
127
* ~~~~~~~~~~{.c}
128
* if ( aerospike_connect(&as, &err) != AEROSPIKE_OK ) {
129
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
130
* }
131
* ~~~~~~~~~~
132
*
133
* The `err` parameter will be populated if an error while attempting to
134
* connect to the database. See as_error, for more information on error
135
* handling.
136
*
137
* An aerospike object internally keeps cluster state and maintains connection pools to the cluster.
138
* The same aerospike object should be reused by the application for database operations
139
* to a given cluster.
140
*
141
* If the application requires connecting to multiple Aerospike clusters, the application must
142
* create multiple aerospike objects, each connecting to a different cluster.
143
*
144
* ## Disconnecting
145
*
146
* When the connection to the database is not longer required, then the
147
* connection to the cluster can be closed via `aerospike_close()`:
148
*
149
* ~~~~~~~~~~{.c}
150
* aerospike_close(&as, &err);
151
* ~~~~~~~~~~
152
*
153
* ## Destruction
154
*
155
* When the client is not longer required, the client and its resources should
156
* be releases via `aerospike_destroy()`:
157
*
158
* ~~~~~~~~~~{.c}
159
* aerospike_destroy(&as);
160
* ~~~~~~~~~~
161
*
162
* @ingroup client_objects
163
*/
164
typedef
struct
aerospike_s {
165
166
/**
167
* @private
168
* If true, then as_query_destroy() will free this instance.
169
*/
170
bool
_free;
171
172
/**
173
* @private
174
* Cluster state.
175
* This is for internal use only. Do not use this in the application.
176
*/
177
struct
cl_cluster_s
* cluster;
178
179
/**
180
* client configuration
181
*/
182
as_config
config;
183
184
/**
185
* client logging
186
*/
187
as_log
log;
188
189
}
aerospike
;
190
191
/******************************************************************************
192
* FUNCTIONS
193
*****************************************************************************/
194
195
/**
196
* Initialize a stack allocated aerospike instance.
197
*
198
* The config parameter can be an instance of `as_config` or `NULL`. If `NULL`,
199
* then the default configuration will be used.
200
*
201
* ~~~~~~~~~~{.c}
202
* aerospike as;
203
* aerospike_init(&as, &config);
204
* ~~~~~~~~~~
205
*
206
* Once you are finished using the instance, then you should destroy it via the
207
* `aerospike_destroy()` function.
208
*
209
* @param as The aerospike instance to initialize.
210
* @param config The configuration to use for the instance.
211
*
212
* @returns the initialized aerospike instance
213
*
214
* @see config for information on configuring the client.
215
*
216
* @relates aerospike
217
*/
218
aerospike
*
aerospike_init
(
aerospike
* as,
as_config
* config);
219
220
/**
221
* Creates a new heap allocated aerospike instance.
222
*
223
* ~~~~~~~~~~{.c}
224
* aerospike * as = aerospike_new(&config);
225
* ~~~~~~~~~~
226
*
227
* Once you are finished using the instance, then you should destroy it via the
228
* `aerospike_destroy()` function.
229
*
230
* @param config The configuration to use for the instance.
231
*
232
* @returns a new aerospike instance
233
*
234
* @see config for information on configuring the client.
235
*
236
* @relates aerospike
237
*/
238
aerospike
*
aerospike_new
(
as_config
* config);
239
240
/**
241
* Destroy the aerospike instance and associated resources.
242
*
243
* ~~~~~~~~~~{.c}
244
* aerospike_destroy(&as);
245
* ~~~~~~~~~~
246
*
247
* @param as The aerospike instance to destroy
248
*
249
* @relates aerospike
250
*/
251
void
aerospike_destroy
(
aerospike
* as);
252
253
/**
254
* Connect an aerospike instance to the cluster.
255
*
256
* ~~~~~~~~~~{.c}
257
* aerospike_connect(&as, &err);
258
* ~~~~~~~~~~
259
*
260
* Once you are finished using the connection, then you must close it via
261
* the `aerospike_close()` function.
262
*
263
* If connect fails, then you do not need to call `aerospike_close()`.
264
*
265
* @param as The aerospike instance to connect to a cluster.
266
* @param err If an error occurs, the err will be populated.
267
*
268
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
269
*
270
* @relates aerospike
271
*/
272
as_status
aerospike_connect
(
aerospike
* as,
as_error
* err);
273
274
/**
275
* Close connections to the cluster.
276
*
277
* ~~~~~~~~~~{.c}
278
* aerospike_close(&as, &err);
279
* ~~~~~~~~~~
280
*
281
* @param as The aerospike instance to disconnect from a cluster.
282
* @param err If an error occurs, the err will be populated.
283
*
284
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
285
*
286
* @relates aerospike
287
*/
288
as_status
aerospike_close
(
aerospike
* as,
as_error
* err);
289