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