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-2017 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  * The Aerospike C client allows you to build C/C++ applications to store and retrieve data from the
25  * Aerospike cluster. The C client is a smart client that periodically pings nodes for cluster
26  * status and manages interactions with the cluster. The following functionality is supported.
27  *
28  * - Database commands
29  * - Key/Value
30  * - Map/List collections
31  * - Batch read
32  * - Scan
33  * - Secondary index query
34  * - User defined Lua functions
35  * - Both synchronous and asynchronous command models
36  * - Asynchronous model supports the following event frameworks.
37  * - libev
38  * - libevent
39  * - libuv
40  * - Thread safe API
41  * - Shared memory cluster tend state for multi-process applications
42  * - TLS secure sockets
43  *
44  * See <a href="modules.html">Modules</a> for an API overview.
45  *
46  * See <a href="http://www.aerospike.com/docs/client/c">Developer Guide</a> for installation
47  * instructions and example code.
48  */
49 
50 /**
51  * @defgroup client_objects Client Objects
52  */
53 
54 /**
55  * @defgroup client_operations Client Operations
56  *
57  * Client operations require an initialized @ref aerospike client.
58  */
59 
60 /**
61  * @defgroup aerospike_t Client Types
62  */
63 
64 /**
65  * @defgroup client_utilities Utilities
66  * @{
67  * @defgroup stringmap_t StringMap
68  * @}
69  */
70 
71 #include <aerospike/as_error.h>
72 #include <aerospike/as_config.h>
73 #include <aerospike/as_log.h>
74 #include <aerospike/as_status.h>
75 #include <stdbool.h>
76 
77 #ifdef __cplusplus
78 extern "C" {
79 #endif
80 
81 /******************************************************************************
82  * TYPES
83  *****************************************************************************/
84 
85 /**
86  * @private
87  * Forward declaration of a cluster object.
88  */
89 struct as_cluster_s;
90 
91 /**
92  * An instance of @ref aerospike is required to connect to and execute
93  * operations against an Aerospike Database cluster.
94  *
95  * ## Configuration
96  *
97  * An initialized client configuration is required to initialize a
98  * @ref aerospike client. See as_config for details on configuration options.
99  *
100  * At a minimum, a configuration needs to be initialized and have at least
101  * one host defined:
102  *
103  * ~~~~~~~~~~{.c}
104  * as_config config;
105  * as_config_init(&config);
106  * as_config_add_host(&config, "127.0.0.1", 3000);
107  * ~~~~~~~~~~
108  *
109  * Once connected to a host in the cluster, then client will gather information
110  * about the cluster, including all other nodes in the cluster. So, all that
111  * is needed is a single valid host. Multiple hosts can still be provided in
112  * case the first host is not currently active.
113  *
114  * ## Initialization
115  *
116  * An initialized @ref aerospike object is required to connect to the
117  * database. Initialization requires a configuration to bind to the client
118  * instance.
119  *
120  * The @ref aerospike object can be initialized via either:
121  *
122  * - aerospike_init() — Initialize a stack allocated @ref aerospike.
123  * - aerospike_new() — Create and initialize a heap allocated @ref aerospike.
124  *
125  * Both initialization functions require a configuration. Once initialized, the ownership
126  * of the as_config instance fields are transferred to @ref aerospike. The user should never
127  * call as_config_destroy() directly.
128  *
129  * The following uses a stack allocated @ref aerospike and initializes it
130  * with aerospike_init():
131  *
132  * ~~~~~~~~~~{.c}
133  * aerospike as;
134  * aerospike_init(&as, &config);
135  * ~~~~~~~~~~
136  *
137  * ## Connecting
138  *
139  * An application can connect to the database with an initialized
140  * @ref aerospike. The client will be connected if `aerospike_connect()` completes
141  * successfully:
142  *
143  * ~~~~~~~~~~{.c}
144  * if (aerospike_connect(&as, &err) != AEROSPIKE_OK) {
145  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
146  * }
147  * ~~~~~~~~~~
148  *
149  * The `err` parameter will be populated if an error while attempting to
150  * connect to the database. See as_error, for more information on error
151  * handling.
152  *
153  * An aerospike object internally keeps cluster state and maintains connection pools to the cluster.
154  * The same aerospike object should be reused by the application for database operations
155  * to a given cluster.
156  *
157  * If the application requires connecting to multiple Aerospike clusters, the application must
158  * create multiple aerospike objects, each connecting to a different cluster.
159  *
160  * ## Disconnecting
161  *
162  * When the connection to the database is not longer required, then the
163  * connection to the cluster can be closed via `aerospike_close()`:
164  *
165  * ~~~~~~~~~~{.c}
166  * aerospike_close(&as, &err);
167  * ~~~~~~~~~~
168  *
169  * ## Destruction
170  *
171  * When the client is not longer required, the client and its resources should
172  * be releases via `aerospike_destroy()`:
173  *
174  * ~~~~~~~~~~{.c}
175  * aerospike_destroy(&as);
176  * ~~~~~~~~~~
177  *
178  * @ingroup client_objects
179  */
180 typedef struct aerospike_s {
181 
182  /**
183  * @private
184  * If true, then aerospike_destroy() will free this instance.
185  */
186  bool _free;
187 
188  /**
189  * @private
190  * Cluster state.
191  */
192  struct as_cluster_s * cluster;
193 
194  /**
195  * Client configuration.
196  */
198 
199 } aerospike;
200 
201 /******************************************************************************
202  * FUNCTIONS
203  *****************************************************************************/
204 
205 /**
206  * Initialize a stack allocated aerospike instance.
207  *
208  * The config parameter can be an instance of `as_config` or `NULL`. If `NULL`,
209  * then the default configuration will be used.
210  *
211  * Ownership of the as_config instance fields are transferred to @ref aerospike.
212  * The user should never call as_config_destroy() directly.
213  *
214  * ~~~~~~~~~~{.c}
215  * aerospike as;
216  * aerospike_init(&as, &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 as The aerospike instance to initialize.
223  * @param config The configuration to use for the instance.
224  *
225  * @returns the initialized aerospike instance
226  *
227  * @see config for information on configuring the client.
228  *
229  * @relates aerospike
230  */
231 aerospike*
232 aerospike_init(aerospike* as, as_config* config);
233 
234 /**
235  * Creates a new heap allocated aerospike instance.
236  *
237  * Ownership of the as_config instance fields are transferred to @ref aerospike.
238  * The user should never call as_config_destroy() directly.
239  *
240  * ~~~~~~~~~~{.c}
241  * aerospike* as = aerospike_new(&config);
242  * ~~~~~~~~~~
243  *
244  * Once you are finished using the instance, then you should destroy it via the
245  * `aerospike_destroy()` function.
246  *
247  * @param config The configuration to use for the instance.
248  *
249  * @returns a new aerospike instance
250  *
251  * @see config for information on configuring the client.
252  *
253  * @relates aerospike
254  */
255 aerospike*
256 aerospike_new(as_config* config);
257 
258 /**
259  * Initialize global lua configuration.
260  *
261  * @param config The lua configuration to use for all cluster instances.
262  */
263 void
265 
266 /**
267  * Destroy the aerospike instance and associated resources.
268  *
269  * ~~~~~~~~~~{.c}
270  * aerospike_destroy(&as);
271  * ~~~~~~~~~~
272  *
273  * @param as The aerospike instance to destroy
274  *
275  * @relates aerospike
276  */
277 void
279 
280 /**
281  * Connect an aerospike instance to the cluster.
282  *
283  * ~~~~~~~~~~{.c}
284  * aerospike_connect(&as, &err);
285  * ~~~~~~~~~~
286  *
287  * Once you are finished using the connection, then you must close it via
288  * the `aerospike_close()` function.
289  *
290  * If connect fails, then you do not need to call `aerospike_close()`.
291  *
292  * @param as The aerospike instance to connect to a cluster.
293  * @param err If an error occurs, the err will be populated.
294  *
295  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
296  *
297  * @relates aerospike
298  */
299 as_status
301 
302 /**
303  * Close connections to the cluster.
304  *
305  * ~~~~~~~~~~{.c}
306  * aerospike_close(&as, &err);
307  * ~~~~~~~~~~
308  *
309  * @param as The aerospike instance to disconnect from a cluster.
310  * @param err If an error occurs, the err will be populated.
311  *
312  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
313  *
314  * @relates aerospike
315  */
316 as_status
318 
319 /**
320  * Is cluster connected to any server nodes.
321  *
322  * ~~~~~~~~~~{.c}
323  * bool connected = aerospike_cluster_is_connected(&as);
324  * ~~~~~~~~~~
325  *
326  * @param as The aerospike instance to check.
327  *
328  * @returns true when cluster is connected.
329  *
330  * @relates aerospike
331  */
332 bool
334 
335 /**
336  * Do all server nodes in the cluster support async pipelining.
337  *
338  * @param as The aerospike instance to check.
339  *
340  * @returns true when all server nodes support pipelining.
341  *
342  * @relates aerospike
343  */
344 bool
346 
347 /**
348  * Should stop socket operation if interrupted by a signal. Default is false which means
349  * the socket operation will be retried until timeout.
350  *
351  * @relates aerospike
352  */
353 void
354 aerospike_stop_on_interrupt(bool stop);
355 
356 /**
357  * Remove records in specified namespace/set efficiently. This method is many orders of magnitude
358  * faster than deleting records one at a time. Works with Aerospike Server versions >= 3.12.
359  *
360  * This asynchronous server call may return before the truncation is complete. The user can still
361  * write new records after the server returns because new records will have last update times
362  * greater than the truncate cutoff (set at the time of truncate call).
363  *
364  * @param as Aerospike instance.
365  * @param err If an error occurs, the err will be populated.
366  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
367  * @param ns Required namespace.
368  * @param set Optional set name. Pass in NULL to delete all sets in namespace.
369  * @param before_nanos Optionally delete records before record last update time.
370  * Units are in nanoseconds since unix epoch (1970-01-01).
371  * If specified, value must be before the current time.
372  * Pass in 0 to delete all records in namespace/set regardless of last update time.
373  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
374  *
375  * @relates aerospike
376  */
377 as_status
378 aerospike_truncate(aerospike* as, as_error* err, as_policy_info* policy, const char* ns, const char* set, uint64_t before_nanos);
379 
380 /**
381  * Refresh the current TLS configuration by reloading its certificate, key, and blacklist files.
382  *
383  * @param as Aerospike instance whose TLS configuration to refresh.
384  * @param err If an error occurs, this will be populated.
385  *
386  * @returns AEROSPIKE_OK on success. Otherwise an error occurred.
387  *
388  * @relates aerospike
389  */
390 as_status
392 
393 #ifdef __cplusplus
394 } // end extern "C"
395 #endif