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-2015 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 String Map
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
* config.hosts[0] = { "127.0.0.1", 3000 };
89
* ~~~~~~~~~~
90
*
91
* A single host is used to specify a host in the database cluster to connect to.
92
* Once connected to a host in the cluster, then client will gather information
93
* about the cluster, including all the other nodes in the cluster. So, all that
94
* is needed is a single valid host, because once a single host is connected, the
95
* then no other hosts in the configuration will be processed.
96
*
97
* ## Initialization
98
*
99
* An initialized @ref aerospike object is required to connect to the
100
* database. Initialization requires a configuration, to bind to the client
101
* instance.
102
*
103
* The @ref aerospike object can be initialized via either:
104
*
105
* - aerospike_init() — Initialize a stack allocated @ref aerospike.
106
* - aerospike_new() — Create and initialize a heap allocated @ref aerospike.
107
*
108
* Both initialization functions require a configuration.
109
*
110
* The following uses a stack allocated @ref aerospike and initializes it
111
* with aerospike_init():
112
*
113
* ~~~~~~~~~~{.c}
114
* aerospike as;
115
* aerospike_init(&as, &config);
116
* ~~~~~~~~~~
117
*
118
* ## Connecting
119
*
120
* An application can connect to the database with an initialized
121
* @ref aerospike. At this point, the client has not connected. The
122
* 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 as_query_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
* ~~~~~~~~~~{.c}
194
* aerospike as;
195
* aerospike_init(&as, &config);
196
* ~~~~~~~~~~
197
*
198
* Once you are finished using the instance, then you should destroy it via the
199
* `aerospike_destroy()` function.
200
*
201
* @param as The aerospike instance to initialize.
202
* @param config The configuration to use for the instance.
203
*
204
* @returns the initialized aerospike instance
205
*
206
* @see config for information on configuring the client.
207
*
208
* @relates aerospike
209
*/
210
aerospike
*
aerospike_init
(
aerospike
* as,
as_config
* config);
211
212
/**
213
* Creates a new heap allocated aerospike instance.
214
*
215
* ~~~~~~~~~~{.c}
216
* aerospike * as = aerospike_new(&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 config The configuration to use for the instance.
223
*
224
* @returns a new aerospike instance
225
*
226
* @see config for information on configuring the client.
227
*
228
* @relates aerospike
229
*/
230
aerospike
*
aerospike_new
(
as_config
* config);
231
232
/**
233
* Destroy the aerospike instance and associated resources.
234
*
235
* ~~~~~~~~~~{.c}
236
* aerospike_destroy(&as);
237
* ~~~~~~~~~~
238
*
239
* @param as The aerospike instance to destroy
240
*
241
* @relates aerospike
242
*/
243
void
aerospike_destroy
(
aerospike
* as);
244
245
/**
246
* Connect an aerospike instance to the cluster.
247
*
248
* ~~~~~~~~~~{.c}
249
* aerospike_connect(&as, &err);
250
* ~~~~~~~~~~
251
*
252
* Once you are finished using the connection, then you must close it via
253
* the `aerospike_close()` function.
254
*
255
* If connect fails, then you do not need to call `aerospike_close()`.
256
*
257
* @param as The aerospike instance to connect to a cluster.
258
* @param err If an error occurs, the err will be populated.
259
*
260
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
261
*
262
* @relates aerospike
263
*/
264
as_status
aerospike_connect
(
aerospike
* as,
as_error
* err);
265
266
/**
267
* Close connections to the cluster.
268
*
269
* ~~~~~~~~~~{.c}
270
* aerospike_close(&as, &err);
271
* ~~~~~~~~~~
272
*
273
* @param as The aerospike instance to disconnect from a cluster.
274
* @param err If an error occurs, the err will be populated.
275
*
276
* @returns AEROSPIKE_OK on success. Otherwise an error occurred.
277
*
278
* @relates aerospike
279
*/
280
as_status
aerospike_close
(
aerospike
* as,
as_error
* err);
281
282
/**
283
* Is cluster connected to any server nodes.
284
*
285
* ~~~~~~~~~~{.c}
286
* bool connected = aerospike_cluster_is_connected(&as);
287
* ~~~~~~~~~~
288
*
289
* @param as The aerospike instance to check.
290
*
291
* @returns true when cluster is connected.
292
*
293
* @relates aerospike
294
*/
295
bool
296
aerospike_cluster_is_connected
(
aerospike
* as);
297
298
#ifdef __cplusplus
299
}
// end extern "C"
300
#endif