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-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <aerospike/as_error.h>
26 #include <aerospike/as_policy.h>
27 #include <aerospike/as_password.h>
28 
29 /******************************************************************************
30  * MACROS
31  *****************************************************************************/
32 
33 #ifdef __linux__
34 /**
35  * Default path to the system UDF files.
36  */
37 #define AS_CONFIG_LUA_SYSTEM_PATH "/opt/aerospike/client/sys/udf/lua"
38 
39 /**
40  * Default path to the user UDF files.
41  */
42 #define AS_CONFIG_LUA_USER_PATH "/opt/aerospike/client/usr/udf/lua"
43 #endif
44 
45 #ifdef __APPLE__
46 /**
47  * Default path to the system UDF files.
48  */
49 #define AS_CONFIG_LUA_SYSTEM_PATH "/usr/local/aerospike/client/sys/udf/lua"
50 
51 /**
52  * Default path to the user UDF files.
53  */
54 #define AS_CONFIG_LUA_USER_PATH "/usr/local/aerospike/client/usr/udf/lua"
55 #endif
56 
57 /**
58  * The size of path strings
59  */
60 #define AS_CONFIG_PATH_MAX_SIZE 256
61 
62 /**
63  * The maximum string length of path strings
64  */
65 #define AS_CONFIG_PATH_MAX_LEN (AS_CONFIG_PATH_MAX_SIZE - 1)
66 
67 /**
68  * The size of as_config.hosts
69  */
70 #define AS_CONFIG_HOSTS_SIZE 256
71 
72 /******************************************************************************
73  * TYPES
74  *****************************************************************************/
75 
76 /**
77  * Host Information
78  *
79  * @ingroup as_config_object
80  */
81 typedef struct as_config_host_s {
82 
83  /**
84  * Host address
85  */
86  const char * addr;
87 
88  /**
89  * Host port
90  */
91  uint16_t port;
92 
94 
95 /**
96  * IP translation table.
97  *
98  * @ingroup as_config_object
99  */
100 typedef struct as_addr_map_s {
101 
102  /**
103  * Original hostname or IP address in string format.
104  */
105  char * orig;
106 
107  /**
108  * Use this IP address instead.
109  */
110  char * alt;
111 
112 } as_addr_map;
113 
114 /**
115  * lua module config
116  *
117  * @ingroup as_config_object
118  */
119 typedef struct as_config_lua_s {
120 
121  /**
122  * Enable caching of UDF files in the client
123  * application.
124  */
126 
127  /**
128  * The path to the system UDF files. These UDF files
129  * are installed with the aerospike client library.
130  * Default location defined in: AS_CONFIG_LUA_SYSTEM_PATH
131  */
132  char system_path[AS_CONFIG_PATH_MAX_SIZE];
133 
134  /**
135  * The path to user's UDF files.
136  * Default location defined in: AS_CONFIG_LUA_USER_PATH
137  */
138  char user_path[AS_CONFIG_PATH_MAX_SIZE];
139 
140 } as_config_lua;
141 
142 /**
143  * The `as_config` contains the settings for the `aerospike` client. Including
144  * default policies, seed hosts in the cluster and other settings.
145  *
146  * ## Initialization
147  *
148  * Before using as_config, you must first initialize it. This will setup the
149  * default values.
150  *
151  * ~~~~~~~~~~{.c}
152  * as_config config;
153  * as_config_init(&config);
154  * ~~~~~~~~~~
155  *
156  * Once initialized, you can populate the values.
157  *
158  * ## Seed Hosts
159  *
160  * The client will require at least one seed host defined in the
161  * configuration. The seed host is defined in `as_config.hosts`.
162  *
163  * ~~~~~~~~~~{.c}
164  * as_config_add_host(&config, "127.0.0.1", 3000);
165  * ~~~~~~~~~~
166  *
167  * You can define up to 256 hosts for the seed. The client will iterate over
168  * the list until it connects with one of the hosts.
169  *
170  * ## Policies
171  *
172  * The configuration also defines default policies for the application. The
173  * `as_config_init()` function already presets default values for the policies.
174  *
175  * Policies define the behavior of the client, which can be global across
176  * operations, global to a single operation, or local to a single use of an
177  * operation.
178  *
179  * Each database operation accepts a policy for that operation as an a argument.
180  * This is considered a local policy, and is a single use policy. This policy
181  * supersedes any global policy defined.
182  *
183  * If a value of the policy is not defined, then the rule is to fallback to the
184  * global policy for that operation. If the global policy for that operation is
185  * undefined, then the global default value will be used.
186  *
187  * If you find that you have behavior that you want every use of an operation
188  * to utilize, then you can specify the default policy in as_config.policies.
189  *
190  * For example, the `aerospike_key_put()` operation takes an `as_policy_write`
191  * policy. If you find yourself setting the `key` policy value for every call
192  * to `aerospike_key_put()`, then you may find it beneficial to set the global
193  * `as_policy_write` in `as_policies.write`, which all write operations will use.
194  *
195  * ~~~~~~~~~~{.c}
196  * config.policies.write.key = AS_POLICY_KEY_SEND;
197  * ~~~~~~~~~~
198  *
199  * If you find that you want to use a policy value across all operations, then
200  * you may find it beneficial to set the default policy value for that policy
201  * value.
202  *
203  * For example, if you keep setting the key policy value to
204  * `AS_POLICY_KEY_SEND`, then you may want to just set `as_policies.key`. This
205  * will set the global default value for the policy value. So, if an global
206  * operation policy or a local operation policy does not define a value, then
207  * this value will be used.
208  *
209  * ~~~~~~~~~~{.c}
210  * config.policies.key = AS_POLICY_KEY_SEND;
211  * ~~~~~~~~~~
212  *
213  * Global default policy values:
214  * - as_policies.timeout
215  * - as_policies.retry
216  * - as_policies.key
217  * - as_policies.gen
218  * - as_policies.exists
219  *
220  * Global operation policies:
221  * - as_policies.read
222  * - as_policies.write
223  * - as_policies.operate
224  * - as_policies.remove
225  * - as_policies.query
226  * - as_policies.scan
227  * - as_policies.info
228  *
229  *
230  * ## User-Defined Function Settings
231  *
232  * If you are using using user-defined functions (UDF) for processing query
233  * results (i.e aggregations), then you will find it useful to set the
234  * `mod_lua` settings. Of particular importance is the `mod_lua.user_path`,
235  * which allows you to define a path to where the client library will look for
236  * Lua files for processing.
237  *
238  * ~~~~~~~~~~{.c}
239  * strcpy(config.mod_lua.user_path, "/home/me/lua");
240  * ~~~~~~~~~~
241  *
242  * @ingroup client_objects
243  */
244 typedef struct as_config_s {
245 
246  /**
247  * User authentication to cluster. Leave empty for clusters running without restricted access.
248  */
249  char user[AS_USER_SIZE];
250 
251  /**
252  * Password authentication to cluster. The password will be stored by the client and sent to
253  * server in hashed format. Leave empty for clusters running without restricted access.
254  */
255  char password[AS_PASSWORD_HASH_SIZE];
256 
257  /**
258  * A IP translation table is used in cases where different clients use different server
259  * IP addresses. This may be necessary when using clients from both inside and outside
260  * a local area network. Default is no translation.
261  *
262  * The key is the IP address returned from friend info requests to other servers. The
263  * value is the real IP address used to connect to the server.
264  *
265  * A deep copy of ip_map is performed in aerospike_connect(). The caller is
266  * responsible for memory deallocation of the original data structure.
267  */
269 
270  /**
271  * Length of ip_map array.
272  * Default: 0
273  */
274  uint32_t ip_map_size;
275 
276  /**
277  * Estimate of incoming threads concurrently using synchronous methods in the client instance.
278  * This field is used to size the synchronous connection pool for each server node.
279  * Default: 300
280  */
281  uint32_t max_threads;
282 
283  /**
284  * @private
285  * Not currently used.
286  * Maximum socket idle in seconds. Socket connection pools will discard sockets
287  * that have been idle longer than the maximum.
288  * Default: 14
289  */
291 
292  /**
293  * Initial host connection timeout in milliseconds. The timeout when opening a connection
294  * to the server host for the first time.
295  * Default: 1000
296  */
297  uint32_t conn_timeout_ms;
298 
299  /**
300  * Polling interval in milliseconds for cluster tender
301  * Default: 1000
302  */
303  uint32_t tender_interval;
304 
305  /**
306  * Count of entries in hosts array.
307  */
308  uint32_t hosts_size;
309 
310  /**
311  * (seed) hosts
312  * Populate with one or more hosts in the cluster
313  * that you intend to connect with.
314  */
316 
317  /**
318  * Client policies
319  */
321 
322  /**
323  * lua config
324  */
326 
327 } as_config;
328 
329 /******************************************************************************
330  * FUNCTIONS
331  *****************************************************************************/
332 
333 /**
334  * Initialize the configuration to default values.
335  *
336  * You should do this to ensure the configuration has valid values, before
337  * populating it with custom options.
338  *
339  * ~~~~~~~~~~{.c}
340  * as_config config;
341  * as_config_init(&config);
342  * as_config_add_host(&config, "127.0.0.1", 3000);
343  * ~~~~~~~~~~
344  *
345  * @param c The configuration to initialize.
346  *
347  * @return The initialized configuration on success. Otherwise NULL.
348  *
349  * @relates as_config
350  */
352 
353 /**
354  * Add host to seed the cluster.
355  *
356  * ~~~~~~~~~~{.c}
357  * as_config config;
358  * as_config_init(&config);
359  * as_config_add_host(&config, "127.0.0.1", 3000);
360  * ~~~~~~~~~~
361  *
362  * @relates as_config
363  */
364 static inline void
365 as_config_add_host(as_config* config, const char* addr, uint16_t port)
366 {
367  as_config_host* host = &config->hosts[config->hosts_size++];
368  host->addr = addr;
369  host->port = port;
370 }
371 
372 /**
373  * User authentication for servers with restricted access. The password will be stored by the
374  * client and sent to server in hashed format.
375  *
376  * ~~~~~~~~~~{.c}
377  * as_config config;
378  * as_config_init(&config);
379  * as_config_set_user(&config, "charlie", "mypassword");
380  * ~~~~~~~~~~
381  *
382  * @relates as_config
383  */
384 bool
385 as_config_set_user(as_config* config, const char* user, const char* password);
uint32_t tender_interval
Definition: as_config.h:303
uint32_t conn_timeout_ms
Definition: as_config.h:297
#define AS_USER_SIZE
Definition: as_password.h:24
bool as_config_set_user(as_config *config, const char *user, const char *password)
as_addr_map * ip_map
Definition: as_config.h:268
as_config * as_config_init(as_config *c)
uint32_t max_threads
Definition: as_config.h:281
#define AS_CONFIG_HOSTS_SIZE
Definition: as_config.h:70
as_config_lua lua
Definition: as_config.h:325
uint32_t hosts_size
Definition: as_config.h:308
uint32_t ip_map_size
Definition: as_config.h:274
const char * addr
Definition: as_config.h:86
static void as_config_add_host(as_config *config, const char *addr, uint16_t port)
Definition: as_config.h:365
as_policies policies
Definition: as_config.h:320
uint16_t port
Definition: as_config.h:91
#define AS_CONFIG_PATH_MAX_SIZE
Definition: as_config.h:60
as_config_host hosts[AS_CONFIG_HOSTS_SIZE]
Definition: as_config.h:315
uint32_t max_socket_idle_sec
Definition: as_config.h:290
bool cache_enabled
Definition: as_config.h:125
char * alt
Definition: as_config.h:110
#define AS_PASSWORD_HASH_SIZE
Definition: as_password.h:29
char * orig
Definition: as_config.h:105