All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_config.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 #include <aerospike/as_error.h>
20 #include <aerospike/as_policy.h>
21 #include <aerospike/as_password.h>
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 /******************************************************************************
28  * MACROS
29  *****************************************************************************/
30 
31 #ifdef __linux__
32 /**
33  * Default path to the system UDF files.
34  */
35 #define AS_CONFIG_LUA_SYSTEM_PATH "/opt/aerospike/client/sys/udf/lua"
36 
37 /**
38  * Default path to the user UDF files.
39  */
40 #define AS_CONFIG_LUA_USER_PATH "/opt/aerospike/client/usr/udf/lua"
41 #endif
42 
43 #ifdef __APPLE__
44 /**
45  * Default path to the system UDF files.
46  */
47 #define AS_CONFIG_LUA_SYSTEM_PATH "/usr/local/aerospike/client/sys/udf/lua"
48 
49 /**
50  * Default path to the user UDF files.
51  */
52 #define AS_CONFIG_LUA_USER_PATH "/usr/local/aerospike/client/usr/udf/lua"
53 #endif
54 
55 /**
56  * The size of path strings
57  */
58 #define AS_CONFIG_PATH_MAX_SIZE 256
59 
60 /**
61  * The maximum string length of path strings
62  */
63 #define AS_CONFIG_PATH_MAX_LEN (AS_CONFIG_PATH_MAX_SIZE - 1)
64 
65 /**
66  * The size of as_config.hosts
67  */
68 #define AS_CONFIG_HOSTS_SIZE 256
69 
70 /******************************************************************************
71  * TYPES
72  *****************************************************************************/
73 
74 /**
75  * Host Information
76  *
77  * @ingroup as_config_object
78  */
79 typedef struct as_config_host_s {
80 
81  /**
82  * Host address
83  */
84  const char * addr;
85 
86  /**
87  * Host port
88  */
89  uint16_t port;
90 
92 
93 /**
94  * IP translation table.
95  *
96  * @ingroup as_config_object
97  */
98 typedef struct as_addr_map_s {
99 
100  /**
101  * Original hostname or IP address in string format.
102  */
103  char * orig;
104 
105  /**
106  * Use this IP address instead.
107  */
108  char * alt;
109 
110 } as_addr_map;
111 
112 /**
113  * lua module config
114  *
115  * @ingroup as_config_object
116  */
117 typedef struct as_config_lua_s {
118 
119  /**
120  * Enable caching of UDF files in the client
121  * application.
122  */
124 
125  /**
126  * The path to the system UDF files. These UDF files
127  * are installed with the aerospike client library.
128  * Default location defined in: AS_CONFIG_LUA_SYSTEM_PATH
129  */
130  char system_path[AS_CONFIG_PATH_MAX_SIZE];
131 
132  /**
133  * The path to user's UDF files.
134  * Default location defined in: AS_CONFIG_LUA_USER_PATH
135  */
136  char user_path[AS_CONFIG_PATH_MAX_SIZE];
137 
138 } as_config_lua;
139 
140 /**
141  * The `as_config` contains the settings for the `aerospike` client. Including
142  * default policies, seed hosts in the cluster and other settings.
143  *
144  * ## Initialization
145  *
146  * Before using as_config, you must first initialize it. This will setup the
147  * default values.
148  *
149  * ~~~~~~~~~~{.c}
150  * as_config config;
151  * as_config_init(&config);
152  * ~~~~~~~~~~
153  *
154  * Once initialized, you can populate the values.
155  *
156  * ## Seed Hosts
157  *
158  * The client will require at least one seed host defined in the
159  * configuration. The seed host is defined in `as_config.hosts`.
160  *
161  * ~~~~~~~~~~{.c}
162  * as_config_add_host(&config, "127.0.0.1", 3000);
163  * ~~~~~~~~~~
164  *
165  * You can define up to 256 hosts for the seed. The client will iterate over
166  * the list until it connects with one of the hosts.
167  *
168  * ## Policies
169  *
170  * The configuration also defines default policies for the application. The
171  * `as_config_init()` function already presets default values for the policies.
172  *
173  * Policies define the behavior of the client, which can be global across
174  * operations, global to a single operation, or local to a single use of an
175  * operation.
176  *
177  * Each database operation accepts a policy for that operation as an a argument.
178  * This is considered a local policy, and is a single use policy. This policy
179  * supersedes any global policy defined.
180  *
181  * If a value of the policy is not defined, then the rule is to fallback to the
182  * global policy for that operation. If the global policy for that operation is
183  * undefined, then the global default value will be used.
184  *
185  * If you find that you have behavior that you want every use of an operation
186  * to utilize, then you can specify the default policy in as_config.policies.
187  *
188  * For example, the `aerospike_key_put()` operation takes an `as_policy_write`
189  * policy. If you find yourself setting the `key` policy value for every call
190  * to `aerospike_key_put()`, then you may find it beneficial to set the global
191  * `as_policy_write` in `as_policies.write`, which all write operations will use.
192  *
193  * ~~~~~~~~~~{.c}
194  * config.policies.write.key = AS_POLICY_KEY_SEND;
195  * ~~~~~~~~~~
196  *
197  * If you find that you want to use a policy value across all operations, then
198  * you may find it beneficial to set the default policy value for that policy
199  * value.
200  *
201  * For example, if you keep setting the key policy value to
202  * `AS_POLICY_KEY_SEND`, then you may want to just set `as_policies.key`. This
203  * will set the global default value for the policy value. So, if an global
204  * operation policy or a local operation policy does not define a value, then
205  * this value will be used.
206  *
207  * ~~~~~~~~~~{.c}
208  * config.policies.key = AS_POLICY_KEY_SEND;
209  * ~~~~~~~~~~
210  *
211  * Global default policy values:
212  * - as_policies.timeout
213  * - as_policies.retry
214  * - as_policies.key
215  * - as_policies.gen
216  * - as_policies.exists
217  *
218  * Global operation policies:
219  * - as_policies.read
220  * - as_policies.write
221  * - as_policies.operate
222  * - as_policies.remove
223  * - as_policies.query
224  * - as_policies.scan
225  * - as_policies.info
226  *
227  *
228  * ## User-Defined Function Settings
229  *
230  * If you are using using user-defined functions (UDF) for processing query
231  * results (i.e aggregations), then you will find it useful to set the
232  * `mod_lua` settings. Of particular importance is the `mod_lua.user_path`,
233  * which allows you to define a path to where the client library will look for
234  * Lua files for processing.
235  *
236  * ~~~~~~~~~~{.c}
237  * strcpy(config.mod_lua.user_path, "/home/me/lua");
238  * ~~~~~~~~~~
239  *
240  * @ingroup client_objects
241  */
242 typedef struct as_config_s {
243 
244  /**
245  * User authentication to cluster. Leave empty for clusters running without restricted access.
246  */
247  char user[AS_USER_SIZE];
248 
249  /**
250  * Password authentication to cluster. The hashed value of password will be stored by the client
251  * and sent to server in same format. Leave empty for clusters running without restricted access.
252  */
253  char password[AS_PASSWORD_HASH_SIZE];
254 
255  /**
256  * A IP translation table is used in cases where different clients use different server
257  * IP addresses. This may be necessary when using clients from both inside and outside
258  * a local area network. Default is no translation.
259  *
260  * The key is the IP address returned from friend info requests to other servers. The
261  * value is the real IP address used to connect to the server.
262  *
263  * A deep copy of ip_map is performed in aerospike_connect(). The caller is
264  * responsible for memory deallocation of the original data structure.
265  */
267 
268  /**
269  * Length of ip_map array.
270  * Default: 0
271  */
272  uint32_t ip_map_size;
273 
274  /**
275  * Estimate of incoming threads concurrently using synchronous methods in the client instance.
276  * This field is used to size the synchronous connection pool for each server node.
277  * Default: 300
278  */
279  uint32_t max_threads;
280 
281  /**
282  * @private
283  * Not currently used.
284  * Maximum socket idle in seconds. Socket connection pools will discard sockets
285  * that have been idle longer than the maximum.
286  * Default: 14
287  */
289 
290  /**
291  * Initial host connection timeout in milliseconds. The timeout when opening a connection
292  * to the server host for the first time.
293  * Default: 1000
294  */
295  uint32_t conn_timeout_ms;
296 
297  /**
298  * Polling interval in milliseconds for cluster tender
299  * Default: 1000
300  */
301  uint32_t tender_interval;
302 
303  /**
304  * Count of entries in hosts array.
305  */
306  uint32_t hosts_size;
307 
308  /**
309  * (seed) hosts
310  * Populate with one or more hosts in the cluster
311  * that you intend to connect with.
312  */
314 
315  /**
316  * Client policies
317  */
319 
320  /**
321  * lua config
322  */
324 
325  /**
326  * Action to perform if client fails to connect to seed hosts.
327  *
328  * If fail_if_not_connected is true (default), the cluster creation will fail
329  * when all seed hosts are not reachable.
330  *
331  * If fail_if_not_connected is false, an empty cluster will be created and the
332  * client will automatically connect when Aerospike server becomes available.
333  */
335 
336  /**
337  * Indicates if shared memory should be used for cluster tending. Shared memory
338  * is useful when operating in single threaded mode with multiple client processes.
339  * This model is used by wrapper languages such as PHP and Python. When enabled,
340  * the data partition maps are maintained by only one process and all other processes
341  * use these shared memory maps.
342  *
343  * Shared memory should not be enabled for multi-threaded programs.
344  * Default: false
345  */
346  bool use_shm;
347 
348  /**
349  * Shared memory identifier. This identifier should be the same for all applications
350  * that use the Aerospike C client.
351  * Default: 0xA5000000
352  */
353  int shm_key;
354 
355  /**
356  * Shared memory maximum number of server nodes allowed. This value is used to size
357  * the fixed shared memory segment. Leave a cushion between actual server node
358  * count and shm_max_nodes so new nodes can be added without having to reboot the client.
359  * Default: 16
360  */
361  uint32_t shm_max_nodes;
362 
363  /**
364  * Shared memory maximum number of namespaces allowed. This value is used to size
365  * the fixed shared memory segment. Leave a cushion between actual namespaces
366  * and shm_max_namespaces so new namespaces can be added without having to reboot the client.
367  * Default: 8
368  */
370 
371  /**
372  * Take over shared memory cluster tending if the cluster hasn't been tended by this
373  * threshold in seconds.
374  * Default: 30
375  */
377 } as_config;
378 
379 /******************************************************************************
380  * FUNCTIONS
381  *****************************************************************************/
382 
383 /**
384  * Initialize the configuration to default values.
385  *
386  * You should do this to ensure the configuration has valid values, before
387  * populating it with custom options.
388  *
389  * ~~~~~~~~~~{.c}
390  * as_config config;
391  * as_config_init(&config);
392  * as_config_add_host(&config, "127.0.0.1", 3000);
393  * ~~~~~~~~~~
394  *
395  * @param c The configuration to initialize.
396  *
397  * @return The initialized configuration on success. Otherwise NULL.
398  *
399  * @relates as_config
400  */
402 
403 /**
404  * Add host to seed the cluster.
405  *
406  * ~~~~~~~~~~{.c}
407  * as_config config;
408  * as_config_init(&config);
409  * as_config_add_host(&config, "127.0.0.1", 3000);
410  * ~~~~~~~~~~
411  *
412  * @relates as_config
413  */
414 static inline void
415 as_config_add_host(as_config* config, const char* addr, uint16_t port)
416 {
417  as_config_host* host = &config->hosts[config->hosts_size++];
418  host->addr = addr;
419  host->port = port;
420 }
421 
422 /**
423  * User authentication for servers with restricted access. The password will be stored by the
424  * client and sent to server in hashed format.
425  *
426  * ~~~~~~~~~~{.c}
427  * as_config config;
428  * as_config_init(&config);
429  * as_config_set_user(&config, "charlie", "mypassword");
430  * ~~~~~~~~~~
431  *
432  * @relates as_config
433  */
434 bool
435 as_config_set_user(as_config* config, const char* user, const char* password);
436 
437 #ifdef __cplusplus
438 } // end extern "C"
439 #endif
uint32_t tender_interval
Definition: as_config.h:301
uint32_t conn_timeout_ms
Definition: as_config.h:295
uint32_t shm_takeover_threshold_sec
Definition: as_config.h:376
#define AS_USER_SIZE
Definition: as_password.h:28
bool as_config_set_user(as_config *config, const char *user, const char *password)
as_addr_map * ip_map
Definition: as_config.h:266
bool use_shm
Definition: as_config.h:346
bool fail_if_not_connected
Definition: as_config.h:334
as_config * as_config_init(as_config *c)
uint32_t max_threads
Definition: as_config.h:279
#define AS_CONFIG_HOSTS_SIZE
Definition: as_config.h:68
int shm_key
Definition: as_config.h:353
as_config_lua lua
Definition: as_config.h:323
uint32_t shm_max_nodes
Definition: as_config.h:361
uint32_t shm_max_namespaces
Definition: as_config.h:369
uint32_t hosts_size
Definition: as_config.h:306
uint32_t ip_map_size
Definition: as_config.h:272
const char * addr
Definition: as_config.h:84
static void as_config_add_host(as_config *config, const char *addr, uint16_t port)
Definition: as_config.h:415
as_policies policies
Definition: as_config.h:318
uint16_t port
Definition: as_config.h:89
#define AS_CONFIG_PATH_MAX_SIZE
Definition: as_config.h:58
as_config_host hosts[AS_CONFIG_HOSTS_SIZE]
Definition: as_config.h:313
uint32_t max_socket_idle_sec
Definition: as_config.h:288
bool cache_enabled
Definition: as_config.h:123
char * alt
Definition: as_config.h:108
#define AS_PASSWORD_HASH_SIZE
Definition: as_password.h:33
char * orig
Definition: as_config.h:103