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