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