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-2016 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  * Maximum number of synchronous connections allowed per server node. Synchronous transactions
276  * will go through retry logic and potentially fail with error code "AEROSPIKE_ERR_NO_MORE_CONNECTIONS"
277  * if the maximum number of connections would be exceeded.
278  *
279  * The number of connections used per node depends on how many concurrent threads issue
280  * database commands plus sub-threads used for parallel multi-node commands (batch, scan,
281  * and query). One connection will be used for each thread.
282  *
283  * Default: 300
284  */
286 
287  /**
288  * Maximum number of asynchronous (non-pipeline) connections allowed for each node.
289  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
290  * loops are created, then each node/event loop asynchronous (non-pipeline) connection pool
291  * will have a limit of 50. Async transactions will be rejected if the limit would be exceeded.
292  * This variable is ignored if asynchronous event loops are not created.
293  * Default: 300
294  */
296 
297  /**
298  * Maximum number of pipeline connections allowed for each node.
299  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
300  * loops are created, then each node/event loop pipeline connection pool will have a limit of 50.
301  * Async transactions will be rejected if the limit would be exceeded.
302  * This variable is ignored if asynchronous event loops are not created.
303  * Default: 64
304  */
306 
307  /**
308  * Initial host connection timeout in milliseconds. The timeout when opening a connection
309  * to the server host for the first time.
310  * Default: 1000
311  */
312  uint32_t conn_timeout_ms;
313 
314  /**
315  * Polling interval in milliseconds for cluster tender
316  * Default: 1000
317  */
318  uint32_t tender_interval;
319 
320  /**
321  * Number of threads stored in underlying thread pool that is used in batch/scan/query commands.
322  * These commands are often sent to multiple server nodes in parallel threads. A thread pool
323  * improves performance because threads do not have to be created/destroyed for each command.
324  * Calculate your value using the following formula:
325  *
326  * thread_pool_size = (concurrent batch/scan/query commands) * (server nodes)
327  *
328  * Default: 16
329  */
331 
332  /**
333  * Count of entries in hosts array.
334  */
335  uint32_t hosts_size;
336 
337  /**
338  * (seed) hosts
339  * Populate with one or more hosts in the cluster
340  * that you intend to connect with.
341  */
343 
344  /**
345  * Client policies
346  */
348 
349  /**
350  * lua config. This is a global config even though it's located here in cluster config.
351  * This config has been left here to avoid breaking the API.
352  *
353  * The global lua config will only be changed once on first cluster initialization.
354  * A better method for initializing lua configuration is to leave this field alone and
355  * instead call aerospike_init_lua():
356  *
357  * ~~~~~~~~~~{.c}
358  * // Get default global lua configuration.
359  * as_config_lua lua;
360  * as_config_lua_init(&lua);
361  *
362  * // Optionally modify lua defaults.
363  * lua.cache_enabled = <enable lua cache>;
364  * strcpy(lua.system_path, <lua system directory>);
365  * strcpy(lua.user_path, <lua user directory>);
366  *
367  * // Initialize global lua configuration.
368  * aerospike_init_lua(&lua);
369  * ~~~~~~~~~~
370  */
372 
373  /**
374  * Action to perform if client fails to connect to seed hosts.
375  *
376  * If fail_if_not_connected is true (default), the cluster creation will fail
377  * when all seed hosts are not reachable.
378  *
379  * If fail_if_not_connected is false, an empty cluster will be created and the
380  * client will automatically connect when Aerospike server becomes available.
381  */
383 
384  /**
385  * Flag to signify if "services-alternate" should be used instead of "services"
386  * Default : false
387  */
389 
390  /**
391  * Indicates if shared memory should be used for cluster tending. Shared memory
392  * is useful when operating in single threaded mode with multiple client processes.
393  * This model is used by wrapper languages such as PHP and Python. When enabled,
394  * the data partition maps are maintained by only one process and all other processes
395  * use these shared memory maps.
396  *
397  * Shared memory should not be enabled for multi-threaded programs.
398  * Default: false
399  */
400  bool use_shm;
401 
402  /**
403  * Shared memory identifier. This identifier should be the same for all applications
404  * that use the Aerospike C client.
405  * Default: 0xA5000000
406  */
407  int shm_key;
408 
409  /**
410  * Shared memory maximum number of server nodes allowed. This value is used to size
411  * the fixed shared memory segment. Leave a cushion between actual server node
412  * count and shm_max_nodes so new nodes can be added without having to reboot the client.
413  * Default: 16
414  */
415  uint32_t shm_max_nodes;
416 
417  /**
418  * Shared memory maximum number of namespaces allowed. This value is used to size
419  * the fixed shared memory segment. Leave a cushion between actual namespaces
420  * and shm_max_namespaces so new namespaces can be added without having to reboot the client.
421  * Default: 8
422  */
424 
425  /**
426  * Take over shared memory cluster tending if the cluster hasn't been tended by this
427  * threshold in seconds.
428  * Default: 30
429  */
431 } as_config;
432 
433 /******************************************************************************
434  * FUNCTIONS
435  *****************************************************************************/
436 
437 /**
438  * Initialize the configuration to default values.
439  *
440  * You should do this to ensure the configuration has valid values, before
441  * populating it with custom options.
442  *
443  * ~~~~~~~~~~{.c}
444  * as_config config;
445  * as_config_init(&config);
446  * as_config_add_host(&config, "127.0.0.1", 3000);
447  * ~~~~~~~~~~
448  *
449  * @param c The configuration to initialize.
450  *
451  * @return The initialized configuration on success. Otherwise NULL.
452  *
453  * @relates as_config
454  */
456 
457 /**
458  * Add host to seed the cluster.
459  *
460  * ~~~~~~~~~~{.c}
461  * as_config config;
462  * as_config_init(&config);
463  * as_config_add_host(&config, "127.0.0.1", 3000);
464  * ~~~~~~~~~~
465  *
466  * @relates as_config
467  */
468 static inline void
469 as_config_add_host(as_config* config, const char* addr, uint16_t port)
470 {
471  as_config_host* host = &config->hosts[config->hosts_size++];
472  host->addr = addr;
473  host->port = port;
474 }
475 
476 /**
477  * User authentication for servers with restricted access. The password will be stored by the
478  * client and sent to server in hashed format.
479  *
480  * ~~~~~~~~~~{.c}
481  * as_config config;
482  * as_config_init(&config);
483  * as_config_set_user(&config, "charlie", "mypassword");
484  * ~~~~~~~~~~
485  *
486  * @relates as_config
487  */
488 bool
489 as_config_set_user(as_config* config, const char* user, const char* password);
490 
491 /**
492  * Initialize global lua configuration to defaults.
493  */
494 static inline void
496 {
497  lua->cache_enabled = false;
498  strcpy(lua->system_path, AS_CONFIG_LUA_SYSTEM_PATH);
499  strcpy(lua->user_path, AS_CONFIG_LUA_USER_PATH);
500 }
501 
502 #ifdef __cplusplus
503 } // end extern "C"
504 #endif