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
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
* ## Disconnecting
138
*
139
* When the connection to the database is not longer required, then the
140
* connection to the cluster can be closed via `aerospike_close()`:
141
*
142
* ~~~~~~~~~~{.c}
143
* aerospike_close(&as, &err);
144
* ~~~~~~~~~~
145
*
146
* ## Destruction
147
*
148
* When the client is not longer required, the client and its resources should
149
* be releases via `aerospike_destroy()`:
150
*
151
* ~~~~~~~~~~{.c}
152
* aerospike_destroy(&as);
153
* ~~~~~~~~~~
154
*
155
* @note Currently, only a single client instance can be created in an
156
* application. In the next release, you will be able to have
157
* multiple clients in a single application.
158
*
159
* @ingroup client_objects
160
*/
161
typedef
struct
aerospike_s {
162
163
/**
164
* @private
165
* If true, then as_query_destroy() will free this instance.
166
*/
167
bool
_free
;
168
169
/**
170
* @private
171
* Cluster state.
172
* This is for internal use only. Do not use this in the application.
173
*/
174
struct
cl_cluster_s *
cluster
;
175
176
/**
177
* client configuration
178
*/
179
as_config
config
;
180
181
/**
182
* client logging
183
*/
184
as_log
log
;
185
186
}
aerospike
;
187
188
/******************************************************************************
189
* FUNCTIONS
190
*****************************************************************************/
191
192
/**
193
* Initialize a stack allocated aerospike instance.
194
*
195
* The config parameter can be an instance of `as_config` or `NULL`. If `NULL`,
196
* then the default configuration will be used.
197
*
198
* ~~~~~~~~~~{.c}
199
* aerospike as;
200
* aerospike_init(&as, &config);
201
* ~~~~~~~~~~
202
*
203
* Once you are finished using the instance, then you should destroy it via the
204
* `aerospike_destroy()` function.
205
*
206
* @param as The aerospike instance to initialize.
207
* @param config The configuration to use for the instance.
208
*
209
* @returns the initialized aerospike instance
210
*
211
* @see config for information on configuring the client.
212
*
213
* @relates aerospike
214
*/
215
aerospike
*
aerospike_init
(
aerospike
* as,
as_config
* config);
216
217
/**
218
* Creates a new heap allocated aerospike instance.
219
*
220
* ~~~~~~~~~~{.c}
221
* aerospike * as = aerospike_new(&config);
222
* ~~~~~~~~~~
223
*
224
* Once you are finished using the instance, then you should destroy it via the
225
* `aerospike_destroy()` function.
226
*
227
* @param config The configuration to use for the instance.
228
*
229
* @returns a new aerospike instance
230
*
231
* @see config for information on configuring the client.
232
*
233
* @relates aerospike
234
*/
235
aerospike
*
aerospike_new
(
as_config
* config);
236
237
/**
238
* Destroy the aerospike instance and associated resources.
239
*
240
* ~~~~~~~~~~{.c}
241
* aerospike_destroy(&as);
242
* ~~~~~~~~~~
243
*
244
* @param as The aerospike instance to destroy
245
*
246
* @relates aerospike
247
*/
248
void
aerospike_destroy
(
aerospike
* as);
249
250
/**
251
* Connect an aerospike instance to the cluster.
252
*
253
* ~~~~~~~~~~{.c}
254
* aerospike_connect(&as, &err);
255
* ~~~~~~~~~~
256
*
257
* Once you are finished using the connection, then you must close it via
258
* the `aerospike_close()` function.
259
*
260
* If connect fails, then you do not need to call `aerospike_close()`.
261
*
262
* @param as The aerospike instance to connect to a cluster.
263
* @param err If an error occurs, the err will be populated.
264
*
265
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
266
*
267
* @relates aerospike
268
*/
269
as_status
aerospike_connect
(
aerospike
* as,
as_error
* err);
270
271
/**
272
* Close connections to the cluster.
273
*
274
* ~~~~~~~~~~{.c}
275
* aerospike_close(&as, &err);
276
* ~~~~~~~~~~
277
*
278
* @param as The aerospike instance to disconnect from a cluster.
279
* @param err If an error occurs, the err will be populated.
280
*
281
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
282
*
283
* @relates aerospike
284
*/
285
as_status
aerospike_close
(
aerospike
* as,
as_error
* err);
286