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-2015 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 String Map
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 * aerospike_init(aerospike * as, as_config * config);
211 
212 /**
213  * Creates a new heap allocated aerospike instance.
214  *
215  * ~~~~~~~~~~{.c}
216  * aerospike * as = aerospike_new(&config);
217  * ~~~~~~~~~~
218  *
219  * Once you are finished using the instance, then you should destroy it via the
220  * `aerospike_destroy()` function.
221  *
222  * @param config The configuration to use for the instance.
223  *
224  * @returns a new aerospike instance
225  *
226  * @see config for information on configuring the client.
227  *
228  * @relates aerospike
229  */
230 aerospike * aerospike_new(as_config * config);
231 
232 /**
233  * Destroy the aerospike instance and associated resources.
234  *
235  * ~~~~~~~~~~{.c}
236  * aerospike_destroy(&as);
237  * ~~~~~~~~~~
238  *
239  * @param as The aerospike instance to destroy
240  *
241  * @relates aerospike
242  */
243 void aerospike_destroy(aerospike * as);
244 
245 /**
246  * Connect an aerospike instance to the cluster.
247  *
248  * ~~~~~~~~~~{.c}
249  * aerospike_connect(&as, &err);
250  * ~~~~~~~~~~
251  *
252  * Once you are finished using the connection, then you must close it via
253  * the `aerospike_close()` function.
254  *
255  * If connect fails, then you do not need to call `aerospike_close()`.
256  *
257  * @param as The aerospike instance to connect to a cluster.
258  * @param err If an error occurs, the err will be populated.
259  *
260  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
261  *
262  * @relates aerospike
263  */
265 
266 /**
267  * Close connections to the cluster.
268  *
269  * ~~~~~~~~~~{.c}
270  * aerospike_close(&as, &err);
271  * ~~~~~~~~~~
272  *
273  * @param as The aerospike instance to disconnect from a cluster.
274  * @param err If an error occurs, the err will be populated.
275  *
276  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
277  *
278  * @relates aerospike
279  */
281 
282 /**
283  * Is cluster connected to any server nodes.
284  *
285  * ~~~~~~~~~~{.c}
286  * bool connected = aerospike_cluster_is_connected(&as);
287  * ~~~~~~~~~~
288  *
289  * @param as The aerospike instance to check.
290  *
291  * @returns true when cluster is connected.
292  *
293  * @relates aerospike
294  */
295 bool
297 
298 #ifdef __cplusplus
299 } // end extern "C"
300 #endif
as_status aerospike_close(aerospike *as, as_error *err)
as_status
Definition: as_status.h:30
struct as_cluster_s * cluster
Definition: aerospike.h:174
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)
aerospike * aerospike_init(aerospike *as, as_config *config)
bool aerospike_cluster_is_connected(aerospike *as)
bool _free
Definition: aerospike.h:168