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  * 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  * Maximum number of asynchronous (non-pipeline) connections allowed for each node.
283  * Async transactions will be rejected if the maximum async node connections would be exceeded.
284  * This variable is ignored if asynchronous event loops are not created.
285  * Default: 300
286  */
288 
289  /**
290  * Maximum number of pipeline connections allowed for each node.
291  * Pipeline transactions will be rejected if the maximum pipeline node connections would be exceeded.
292  * This variable is ignored if asynchronous event loops are not created.
293  * Default: 300
294  */
296 
297  /**
298  * @private
299  * Not currently used.
300  * Maximum socket idle in seconds. Socket connection pools will discard sockets
301  * that have been idle longer than the maximum.
302  * Default: 55
303  */
305 
306  /**
307  * Initial host connection timeout in milliseconds. The timeout when opening a connection
308  * to the server host for the first time.
309  * Default: 1000
310  */
311  uint32_t conn_timeout_ms;
312 
313  /**
314  * Polling interval in milliseconds for cluster tender
315  * Default: 1000
316  */
317  uint32_t tender_interval;
318 
319  /**
320  * Number of threads stored in underlying thread pool that is used in batch/scan/query commands.
321  * These commands are often sent to multiple server nodes in parallel threads. A thread pool
322  * improves performance because threads do not have to be created/destroyed for each command.
323  * Calculate your value using the following formula:
324  *
325  * thread_pool_size = (concurrent batch/scan/query commands) * (server nodes)
326  *
327  * Default: 16
328  */
330 
331  /**
332  * Count of entries in hosts array.
333  */
334  uint32_t hosts_size;
335 
336  /**
337  * (seed) hosts
338  * Populate with one or more hosts in the cluster
339  * that you intend to connect with.
340  */
342 
343  /**
344  * Client policies
345  */
347 
348  /**
349  * lua config
350  */
352 
353  /**
354  * Action to perform if client fails to connect to seed hosts.
355  *
356  * If fail_if_not_connected is true (default), the cluster creation will fail
357  * when all seed hosts are not reachable.
358  *
359  * If fail_if_not_connected is false, an empty cluster will be created and the
360  * client will automatically connect when Aerospike server becomes available.
361  */
363 
364  /**
365  * Flag to signify if "services-alternate" should be used instead of "services"
366  * Default : false
367  */
369 
370  /**
371  * Indicates if shared memory should be used for cluster tending. Shared memory
372  * is useful when operating in single threaded mode with multiple client processes.
373  * This model is used by wrapper languages such as PHP and Python. When enabled,
374  * the data partition maps are maintained by only one process and all other processes
375  * use these shared memory maps.
376  *
377  * Shared memory should not be enabled for multi-threaded programs.
378  * Default: false
379  */
380  bool use_shm;
381 
382  /**
383  * Shared memory identifier. This identifier should be the same for all applications
384  * that use the Aerospike C client.
385  * Default: 0xA5000000
386  */
387  int shm_key;
388 
389  /**
390  * Shared memory maximum number of server nodes allowed. This value is used to size
391  * the fixed shared memory segment. Leave a cushion between actual server node
392  * count and shm_max_nodes so new nodes can be added without having to reboot the client.
393  * Default: 16
394  */
395  uint32_t shm_max_nodes;
396 
397  /**
398  * Shared memory maximum number of namespaces allowed. This value is used to size
399  * the fixed shared memory segment. Leave a cushion between actual namespaces
400  * and shm_max_namespaces so new namespaces can be added without having to reboot the client.
401  * Default: 8
402  */
404 
405  /**
406  * Take over shared memory cluster tending if the cluster hasn't been tended by this
407  * threshold in seconds.
408  * Default: 30
409  */
411 } as_config;
412 
413 /******************************************************************************
414  * FUNCTIONS
415  *****************************************************************************/
416 
417 /**
418  * Initialize the configuration to default values.
419  *
420  * You should do this to ensure the configuration has valid values, before
421  * populating it with custom options.
422  *
423  * ~~~~~~~~~~{.c}
424  * as_config config;
425  * as_config_init(&config);
426  * as_config_add_host(&config, "127.0.0.1", 3000);
427  * ~~~~~~~~~~
428  *
429  * @param c The configuration to initialize.
430  *
431  * @return The initialized configuration on success. Otherwise NULL.
432  *
433  * @relates as_config
434  */
436 
437 /**
438  * Add host to seed the cluster.
439  *
440  * ~~~~~~~~~~{.c}
441  * as_config config;
442  * as_config_init(&config);
443  * as_config_add_host(&config, "127.0.0.1", 3000);
444  * ~~~~~~~~~~
445  *
446  * @relates as_config
447  */
448 static inline void
449 as_config_add_host(as_config* config, const char* addr, uint16_t port)
450 {
451  as_config_host* host = &config->hosts[config->hosts_size++];
452  host->addr = addr;
453  host->port = port;
454 }
455 
456 /**
457  * User authentication for servers with restricted access. The password will be stored by the
458  * client and sent to server in hashed format.
459  *
460  * ~~~~~~~~~~{.c}
461  * as_config config;
462  * as_config_init(&config);
463  * as_config_set_user(&config, "charlie", "mypassword");
464  * ~~~~~~~~~~
465  *
466  * @relates as_config
467  */
468 bool
469 as_config_set_user(as_config* config, const char* user, const char* password);
470 
471 #ifdef __cplusplus
472 } // end extern "C"
473 #endif