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-2014 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
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 /******************************************************************************
60  * TYPES
61  *****************************************************************************/
62 
63 /**
64  * @private
65  * Forward declaration of a cluster object.
66  */
67 struct as_cluster_s;
68 
69 /**
70  * An instance of @ref aerospike is required to connect to and execute
71  * operations against an Aerospike Database cluster.
72  *
73  * ## Configuration
74  *
75  * An initialized client configuration is required to initialize a
76  * @ref aerospike client. See as_config for details on configuration options.
77  *
78  * At a minimum, a configuration needs to be initialized and have at least
79  * one host defined:
80  *
81  * ~~~~~~~~~~{.c}
82  * as_config config;
83  * as_config_init(&config);
84  * config.hosts[0] = { "127.0.0.1", 3000 };
85  * ~~~~~~~~~~
86  *
87  * A single host is used to specify a host in the database cluster to connect to.
88  * Once connected to a host in the cluster, then client will gather information
89  * about the cluster, including all the other nodes in the cluster. So, all that
90  * is needed is a single valid host, because once a single host is connected, the
91  * then no other hosts in the configuration will be processed.
92  *
93  * ## Initialization
94  *
95  * An initialized @ref aerospike object is required to connect to the
96  * database. Initialization requires a configuration, to bind to the client
97  * instance.
98  *
99  * The @ref aerospike object can be initialized via either:
100  *
101  * - aerospike_init() — Initialize a stack allocated @ref aerospike.
102  * - aerospike_new() — Create and initialize a heap allocated @ref aerospike.
103  *
104  * Both initialization functions require a configuration.
105  *
106  * The following uses a stack allocated @ref aerospike and initializes it
107  * with aerospike_init():
108  *
109  * ~~~~~~~~~~{.c}
110  * aerospike as;
111  * aerospike_init(&as, &config);
112  * ~~~~~~~~~~
113  *
114  * ## Connecting
115  *
116  * An application can connect to the database with an initialized
117  * @ref aerospike. At this point, the client has not connected. The
118  * client will be connected if `aerospike_connect()` completes
119  * successfully:
120  *
121  * ~~~~~~~~~~{.c}
122  * if ( aerospike_connect(&as, &err) != AEROSPIKE_OK ) {
123  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
124  * }
125  * ~~~~~~~~~~
126  *
127  * The `err` parameter will be populated if an error while attempting to
128  * connect to the database. See as_error, for more information on error
129  * handling.
130  *
131  * An aerospike object internally keeps cluster state and maintains connection pools to the cluster.
132  * The same aerospike object should be reused by the application for database operations
133  * to a given cluster.
134  *
135  * If the application requires connecting to multiple Aerospike clusters, the application must
136  * create multiple aerospike objects, each connecting to a different cluster.
137  *
138  * ## Disconnecting
139  *
140  * When the connection to the database is not longer required, then the
141  * connection to the cluster can be closed via `aerospike_close()`:
142  *
143  * ~~~~~~~~~~{.c}
144  * aerospike_close(&as, &err);
145  * ~~~~~~~~~~
146  *
147  * ## Destruction
148  *
149  * When the client is not longer required, the client and its resources should
150  * be releases via `aerospike_destroy()`:
151  *
152  * ~~~~~~~~~~{.c}
153  * aerospike_destroy(&as);
154  * ~~~~~~~~~~
155  *
156  * @ingroup client_objects
157  */
158 typedef struct aerospike_s {
159 
160  /**
161  * @private
162  * If true, then as_query_destroy() will free this instance.
163  */
164  bool _free;
165 
166  /**
167  * @private
168  * Cluster state.
169  */
170  struct as_cluster_s * cluster;
171 
172  /**
173  * client configuration
174  */
176 
177  /**
178  * client logging
179  */
181 
182 } aerospike;
183 
184 /******************************************************************************
185  * FUNCTIONS
186  *****************************************************************************/
187 
188 /**
189  * Initialize a stack allocated aerospike instance.
190  *
191  * The config parameter can be an instance of `as_config` or `NULL`. If `NULL`,
192  * then the default configuration will be used.
193  *
194  * ~~~~~~~~~~{.c}
195  * aerospike as;
196  * aerospike_init(&as, &config);
197  * ~~~~~~~~~~
198  *
199  * Once you are finished using the instance, then you should destroy it via the
200  * `aerospike_destroy()` function.
201  *
202  * @param as The aerospike instance to initialize.
203  * @param config The configuration to use for the instance.
204  *
205  * @returns the initialized aerospike instance
206  *
207  * @see config for information on configuring the client.
208  *
209  * @relates aerospike
210  */
211 aerospike * 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 * aerospike_new(as_config * config);
232 
233 /**
234  * Destroy the aerospike instance and associated resources.
235  *
236  * ~~~~~~~~~~{.c}
237  * aerospike_destroy(&as);
238  * ~~~~~~~~~~
239  *
240  * @param as The aerospike instance to destroy
241  *
242  * @relates aerospike
243  */
244 void aerospike_destroy(aerospike * as);
245 
246 /**
247  * Connect an aerospike instance to the cluster.
248  *
249  * ~~~~~~~~~~{.c}
250  * aerospike_connect(&as, &err);
251  * ~~~~~~~~~~
252  *
253  * Once you are finished using the connection, then you must close it via
254  * the `aerospike_close()` function.
255  *
256  * If connect fails, then you do not need to call `aerospike_close()`.
257  *
258  * @param as The aerospike instance to connect to a cluster.
259  * @param err If an error occurs, the err will be populated.
260  *
261  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
262  *
263  * @relates aerospike
264  */
266 
267 /**
268  * Close connections to the cluster.
269  *
270  * ~~~~~~~~~~{.c}
271  * aerospike_close(&as, &err);
272  * ~~~~~~~~~~
273  *
274  * @param as The aerospike instance to disconnect from a cluster.
275  * @param err If an error occurs, the err will be populated.
276  *
277  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
278  *
279  * @relates aerospike
280  */
282