All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2016 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 StringMap
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  * as_config_add_host(&config, "127.0.0.1", 3000);
89  * ~~~~~~~~~~
90  *
91  * Once connected to a host in the cluster, then client will gather information
92  * about the cluster, including all other nodes in the cluster. So, all that
93  * is needed is a single valid host. Multiple hosts can still be provided in
94  * case the first host is not currently active.
95  *
96  * ## Initialization
97  *
98  * An initialized @ref aerospike object is required to connect to the
99  * database. Initialization requires a configuration to bind to the client
100  * instance.
101  *
102  * The @ref aerospike object can be initialized via either:
103  *
104  * - aerospike_init() — Initialize a stack allocated @ref aerospike.
105  * - aerospike_new() — Create and initialize a heap allocated @ref aerospike.
106  *
107  * Both initialization functions require a configuration. Once initialized, the ownership
108  * of the as_config instance fields are transferred to @ref aerospike. The user should never
109  * call as_config_destroy() directly.
110  *
111  * The following uses a stack allocated @ref aerospike and initializes it
112  * with aerospike_init():
113  *
114  * ~~~~~~~~~~{.c}
115  * aerospike as;
116  * aerospike_init(&as, &config);
117  * ~~~~~~~~~~
118  *
119  * ## Connecting
120  *
121  * An application can connect to the database with an initialized
122  * @ref aerospike. The 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 aerospike_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  */
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  * Ownership of the as_config instance fields are transferred to @ref aerospike.
194  * The user should never call as_config_destroy() directly.
195  *
196  * ~~~~~~~~~~{.c}
197  * aerospike as;
198  * aerospike_init(&as, &config);
199  * ~~~~~~~~~~
200  *
201  * Once you are finished using the instance, then you should destroy it via the
202  * `aerospike_destroy()` function.
203  *
204  * @param as The aerospike instance to initialize.
205  * @param config The configuration to use for the instance.
206  *
207  * @returns the initialized aerospike instance
208  *
209  * @see config for information on configuring the client.
210  *
211  * @relates aerospike
212  */
213 aerospike*
214 aerospike_init(aerospike* as, as_config* config);
215 
216 /**
217  * Creates a new heap allocated aerospike instance.
218  *
219  * Ownership of the as_config instance fields are transferred to @ref aerospike.
220  * The user should never call as_config_destroy() directly.
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*
238 aerospike_new(as_config* config);
239 
240 /**
241  * Initialize global lua configuration.
242  *
243  * @param config The lua configuration to use for all cluster instances.
244  */
245 void
247 
248 /**
249  * Destroy the aerospike instance and associated resources.
250  *
251  * ~~~~~~~~~~{.c}
252  * aerospike_destroy(&as);
253  * ~~~~~~~~~~
254  *
255  * @param as The aerospike instance to destroy
256  *
257  * @relates aerospike
258  */
259 void
261 
262 /**
263  * Connect an aerospike instance to the cluster.
264  *
265  * ~~~~~~~~~~{.c}
266  * aerospike_connect(&as, &err);
267  * ~~~~~~~~~~
268  *
269  * Once you are finished using the connection, then you must close it via
270  * the `aerospike_close()` function.
271  *
272  * If connect fails, then you do not need to call `aerospike_close()`.
273  *
274  * @param as The aerospike instance to connect to 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
283 
284 /**
285  * Close connections to the cluster.
286  *
287  * ~~~~~~~~~~{.c}
288  * aerospike_close(&as, &err);
289  * ~~~~~~~~~~
290  *
291  * @param as The aerospike instance to disconnect from a cluster.
292  * @param err If an error occurs, the err will be populated.
293  *
294  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
295  *
296  * @relates aerospike
297  */
298 as_status
300 
301 /**
302  * Is cluster connected to any server nodes.
303  *
304  * ~~~~~~~~~~{.c}
305  * bool connected = aerospike_cluster_is_connected(&as);
306  * ~~~~~~~~~~
307  *
308  * @param as The aerospike instance to check.
309  *
310  * @returns true when cluster is connected.
311  *
312  * @relates aerospike
313  */
314 bool
316 
317 /**
318  * Do all server nodes in the cluster support async pipelining.
319  *
320  * @param as The aerospike instance to check.
321  *
322  * @returns true when all server nodes support pipelining.
323  *
324  * @relates aerospike
325  */
326 bool
328 
329 /**
330  * Should stop socket operation if interrupted by a signal. Default is false which means
331  * the socket operation will be retried until timeout.
332  *
333  * @relates aerospike
334  */
335 void
336 aerospike_stop_on_interrupt(bool stop);
337 
338 #ifdef __cplusplus
339 } // end extern "C"
340 #endif