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  * 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  */
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*
211 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*
232 aerospike_new(as_config* config);
233 
234 /**
235  * Initialize global lua configuration.
236  *
237  * @param config The lua configuration to use for all cluster instances.
238  */
239 void
241 
242 /**
243  * Destroy the aerospike instance and associated resources.
244  *
245  * ~~~~~~~~~~{.c}
246  * aerospike_destroy(&as);
247  * ~~~~~~~~~~
248  *
249  * @param as The aerospike instance to destroy
250  *
251  * @relates aerospike
252  */
253 void
255 
256 /**
257  * Connect an aerospike instance to the cluster.
258  *
259  * ~~~~~~~~~~{.c}
260  * aerospike_connect(&as, &err);
261  * ~~~~~~~~~~
262  *
263  * Once you are finished using the connection, then you must close it via
264  * the `aerospike_close()` function.
265  *
266  * If connect fails, then you do not need to call `aerospike_close()`.
267  *
268  * @param as The aerospike instance to connect to a cluster.
269  * @param err If an error occurs, the err will be populated.
270  *
271  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
272  *
273  * @relates aerospike
274  */
275 as_status
277 
278 /**
279  * Close connections to the cluster.
280  *
281  * ~~~~~~~~~~{.c}
282  * aerospike_close(&as, &err);
283  * ~~~~~~~~~~
284  *
285  * @param as The aerospike instance to disconnect from a cluster.
286  * @param err If an error occurs, the err will be populated.
287  *
288  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
289  *
290  * @relates aerospike
291  */
292 as_status
294 
295 /**
296  * Is cluster connected to any server nodes.
297  *
298  * ~~~~~~~~~~{.c}
299  * bool connected = aerospike_cluster_is_connected(&as);
300  * ~~~~~~~~~~
301  *
302  * @param as The aerospike instance to check.
303  *
304  * @returns true when cluster is connected.
305  *
306  * @relates aerospike
307  */
308 bool
310 
311 /**
312  * Is cluster connected to any server nodes.
313  *
314  * ~~~~~~~~~~{.c}
315  * bool connected = aerospike_cluster_is_connected(&as);
316  * ~~~~~~~~~~
317  *
318  * @param as The aerospike instance to check.
319  *
320  * @returns true when cluster is connected.
321  *
322  * @relates aerospike
323  */
324 bool
326 
327 /**
328  * Should stop socket operation if interrupted by a signal. Default is false which means
329  * the socket operation will be retried until timeout.
330  *
331  * @relates aerospike
332  */
333 void
334 aerospike_stop_on_interrupt(bool stop);
335 
336 #ifdef __cplusplus
337 } // end extern "C"
338 #endif