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