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-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
as_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
*/
176
struct
as_cluster_s *
cluster
;
177
178
/**
179
* client configuration
180
*/
181
as_config
config
;
182
183
/**
184
* client logging
185
*/
186
as_log
log
;
187
188
}
aerospike
;
189
190
/******************************************************************************
191
* FUNCTIONS
192
*****************************************************************************/
193
194
/**
195
* Initialize a stack allocated aerospike instance.
196
*
197
* The config parameter can be an instance of `as_config` or `NULL`. If `NULL`,
198
* then the default configuration will be used.
199
*
200
* ~~~~~~~~~~{.c}
201
* aerospike as;
202
* aerospike_init(&as, &config);
203
* ~~~~~~~~~~
204
*
205
* Once you are finished using the instance, then you should destroy it via the
206
* `aerospike_destroy()` function.
207
*
208
* @param as The aerospike instance to initialize.
209
* @param config The configuration to use for the instance.
210
*
211
* @returns the initialized aerospike instance
212
*
213
* @see config for information on configuring the client.
214
*
215
* @relates aerospike
216
*/
217
aerospike
*
aerospike_init
(
aerospike
* as,
as_config
* config);
218
219
/**
220
* Creates a new heap allocated aerospike instance.
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
*
aerospike_new
(
as_config
* config);
238
239
/**
240
* Destroy the aerospike instance and associated resources.
241
*
242
* ~~~~~~~~~~{.c}
243
* aerospike_destroy(&as);
244
* ~~~~~~~~~~
245
*
246
* @param as The aerospike instance to destroy
247
*
248
* @relates aerospike
249
*/
250
void
aerospike_destroy
(
aerospike
* as);
251
252
/**
253
* Connect an aerospike instance to the cluster.
254
*
255
* ~~~~~~~~~~{.c}
256
* aerospike_connect(&as, &err);
257
* ~~~~~~~~~~
258
*
259
* Once you are finished using the connection, then you must close it via
260
* the `aerospike_close()` function.
261
*
262
* If connect fails, then you do not need to call `aerospike_close()`.
263
*
264
* @param as The aerospike instance to connect to a cluster.
265
* @param err If an error occurs, the err will be populated.
266
*
267
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
268
*
269
* @relates aerospike
270
*/
271
as_status
aerospike_connect
(
aerospike
* as,
as_error
* err);
272
273
/**
274
* Close connections to the cluster.
275
*
276
* ~~~~~~~~~~{.c}
277
* aerospike_close(&as, &err);
278
* ~~~~~~~~~~
279
*
280
* @param as The aerospike instance to disconnect from a cluster.
281
* @param err If an error occurs, the err will be populated.
282
*
283
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
284
*
285
* @relates aerospike
286
*/
287
as_status
aerospike_close
(
aerospike
* as,
as_error
* err);
288