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-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 as_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  */
176  struct as_cluster_s * cluster;
177 
178  /**
179  * client configuration
180  */
182 
183  /**
184  * client logging
185  */
187 
188 } aerospike;
189 
190 /******************************************************************************
191  * FUNCTIONS
192  *****************************************************************************/
193 
194 /**
195  * Initialize a stack allocated aerospike instance.
196  *
197  * The config parameter can be an instance of `as_config` or `NULL`. If `NULL`,
198  * then the default configuration will be used.
199  *
200  * ~~~~~~~~~~{.c}
201  * aerospike as;
202  * aerospike_init(&as, &config);
203  * ~~~~~~~~~~
204  *
205  * Once you are finished using the instance, then you should destroy it via the
206  * `aerospike_destroy()` function.
207  *
208  * @param as The aerospike instance to initialize.
209  * @param config The configuration to use for the instance.
210  *
211  * @returns the initialized aerospike instance
212  *
213  * @see config for information on configuring the client.
214  *
215  * @relates aerospike
216  */
217 aerospike * aerospike_init(aerospike * as, as_config * config);
218 
219 /**
220  * Creates a new heap allocated aerospike instance.
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 * aerospike_new(as_config * config);
238 
239 /**
240  * Destroy the aerospike instance and associated resources.
241  *
242  * ~~~~~~~~~~{.c}
243  * aerospike_destroy(&as);
244  * ~~~~~~~~~~
245  *
246  * @param as The aerospike instance to destroy
247  *
248  * @relates aerospike
249  */
250 void aerospike_destroy(aerospike * as);
251 
252 /**
253  * Connect an aerospike instance to the cluster.
254  *
255  * ~~~~~~~~~~{.c}
256  * aerospike_connect(&as, &err);
257  * ~~~~~~~~~~
258  *
259  * Once you are finished using the connection, then you must close it via
260  * the `aerospike_close()` function.
261  *
262  * If connect fails, then you do not need to call `aerospike_close()`.
263  *
264  * @param as The aerospike instance to connect to a cluster.
265  * @param err If an error occurs, the err will be populated.
266  *
267  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
268  *
269  * @relates aerospike
270  */
272 
273 /**
274  * Close connections to the cluster.
275  *
276  * ~~~~~~~~~~{.c}
277  * aerospike_close(&as, &err);
278  * ~~~~~~~~~~
279  *
280  * @param as The aerospike instance to disconnect from a cluster.
281  * @param err If an error occurs, the err will be populated.
282  *
283  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
284  *
285  * @relates aerospike
286  */
288 
as_status aerospike_close(aerospike *as, as_error *err)
as_status
Definition: as_status.h:32
struct as_cluster_s * cluster
Definition: aerospike.h:176
Definition: as_log.h:140
void aerospike_destroy(aerospike *as)
as_status aerospike_connect(aerospike *as, as_error *err)
as_config config
Definition: aerospike.h:181
aerospike * aerospike_new(as_config *config)
as_log log
Definition: aerospike.h:186
aerospike * aerospike_init(aerospike *as, as_config *config)
bool _free
Definition: aerospike.h:170