All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
src/include/aerospike/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 
28 /******************************************************************************
29  * MACROS
30  *****************************************************************************/
31 
32 #ifdef __linux__
33 /**
34  * Default path to the system UDF files.
35  */
36 #define AS_CONFIG_LUA_SYSTEM_PATH "/opt/aerospike/client/sys/udf/lua"
37 
38 /**
39  * Default path to the user UDF files.
40  */
41 #define AS_CONFIG_LUA_USER_PATH "/opt/aerospike/client/usr/udf/lua"
42 #endif
43 
44 #ifdef __APPLE__
45 /**
46  * Default path to the system UDF files.
47  */
48 #define AS_CONFIG_LUA_SYSTEM_PATH "/usr/local/aerospike/client/sys/udf/lua"
49 
50 /**
51  * Default path to the user UDF files.
52  */
53 #define AS_CONFIG_LUA_USER_PATH "/usr/local/aerospike/client/usr/udf/lua"
54 #endif
55 
56 /**
57  * The size of path strings
58  */
59 #define AS_CONFIG_PATH_MAX_SIZE 256
60 
61 /**
62  * The maximum string length of path strings
63  */
64 #define AS_CONFIG_PATH_MAX_LEN (AS_CONFIG_PATH_MAX_SIZE - 1)
65 
66 /**
67  * The size of as_config.hosts
68  */
69 #define AS_CONFIG_HOSTS_SIZE 256
70 
71 /******************************************************************************
72  * TYPES
73  *****************************************************************************/
74 
75 /**
76  * Host Information
77  *
78  * @ingroup as_config_object
79  */
80 typedef struct as_config_host_s {
81 
82  /**
83  * Host address
84  */
85  const char * addr;
86 
87  /**
88  * Host port
89  */
90  uint16_t port;
91 
93 
94 
95 /**
96  * lua module config
97  *
98  * @ingroup as_config_object
99  */
100 typedef struct as_config_lua_s {
101 
102  /**
103  * Enable caching of UDF files in the client
104  * application.
105  */
107 
108  /**
109  * The path to the system UDF files. These UDF files
110  * are installed with the aerospike client library.
111  * Default location defined in: AS_CONFIG_LUA_SYSTEM_PATH
112  */
113  char system_path[AS_CONFIG_PATH_MAX_SIZE];
114 
115  /**
116  * The path to user's UDF files.
117  * Default location defined in: AS_CONFIG_LUA_USER_PATH
118  */
119  char user_path[AS_CONFIG_PATH_MAX_SIZE];
120 
121 } as_config_lua;
122 
123 /**
124  * The `as_config` contains the settings for the `aerospike` client. Including
125  * default policies, seed hosts in the cluster and other settings.
126  *
127  * ## Initialization
128  *
129  * Before using as_config, you must first initialize it. This will setup the
130  * default values.
131  *
132  * ~~~~~~~~~~{.c}
133  * as_config config;
134  * as_config_init(&config);
135  * ~~~~~~~~~~
136  *
137  * Once initialized, you can populate the values.
138  *
139  * ## Seed Hosts
140  *
141  * The client will require at least one seed host defined in the
142  * configuration. The seed host is defined in `as_config.hosts`.
143  *
144  * ~~~~~~~~~~{.c}
145  * config.hosts[0] = { .addr = "127.0.0.1", .port = 3000 };
146  * ~~~~~~~~~~
147  *
148  * You can define up to 16 hosts for the seed. The client will iterate over
149  * the list until it connects with one of the hosts.
150  *
151  * ## Policies
152  *
153  * The configuration also defines default policies for the application. The
154  * `as_config_init()` function already presets default values for the policies.
155  *
156  * Policies define the behavior of the client, which can be global across
157  * operations, global to a single operation, or local to a single use of an
158  * operation.
159  *
160  * Each database operation accepts a policy for that operation as an a argument.
161  * This is considered a local policy, and is a single use policy. This policy
162  * supersedes any global policy defined.
163  *
164  * If a value of the policy is not defined, then the rule is to fallback to the
165  * global policy for that operation. If the global policy for that operation is
166  * undefined, then the global default value will be used.
167  *
168  * If you find that you have behavior that you want every use of an operation
169  * to utilize, then you can specify the default policy in as_config.policies.
170  *
171  * For example, the `aerospike_key_put()` operation takes an `as_policy_write`
172  * policy. If you find yourself setting the `key` policy value for every call
173  * to `aerospike_key_put()`, then you may find it beneficial to set the global
174  * `as_policy_write` in `as_policies.write`, which all write operations will use.
175  *
176  * ~~~~~~~~~~{.c}
177  * config.policies.write.key = AS_POLICY_KEY_SEND;
178  * ~~~~~~~~~~
179  *
180  * If you find that you want to use a policy value across all operations, then
181  * you may find it beneficial to set the default policy value for that policy
182  * value.
183  *
184  * For example, if you keep setting the key policy value to
185  * `AS_POLICY_KEY_SEND`, then you may want to just set `as_policies.key`. This
186  * will set the global default value for the policy value. So, if an global
187  * operation policy or a local operation policy does not define a value, then
188  * this value will be used.
189  *
190  * ~~~~~~~~~~{.c}
191  * config.policies.key = AS_POLICY_KEY_SEND;
192  * ~~~~~~~~~~
193  *
194  * Global default policy values:
195  * - as_policies.timeout
196  * - as_policies.retry
197  * - as_policies.key
198  * - as_policies.gen
199  * - as_policies.exists
200  *
201  * Global operation policies:
202  * - as_policies.read
203  * - as_policies.write
204  * - as_policies.operate
205  * - as_policies.remove
206  * - as_policies.query
207  * - as_policies.scan
208  * - as_policies.info
209  *
210  *
211  * ## User-Defined Function Settings
212  *
213  * If you are using using user-defined functions (UDF) for processing query
214  * results (i.e aggregations), then you will find it useful to set the
215  * `mod_lua` settings. Of particular importance is the `mod_lua.user_path`,
216  * which allows you to define a path to where the client library will look for
217  * Lua files for processing.
218  *
219  * ~~~~~~~~~~{.c}
220  * strcpy(config.mod_lua.user_path, "/home/me/lua");
221  * ~~~~~~~~~~
222  *
223  * @ingroup client_objects
224  */
225 typedef struct as_config_s {
226 
227  /**
228  * Polling interval in milliseconds for cluster tender
229  */
230  uint32_t tender_interval;
231 
232  /**
233  * Client policies
234  */
236 
237  /**
238  * (seed) hosts
239  * Populate with one or more hosts in the cluster
240  * that you intend to connect with.
241  */
243 
244  /**
245  * lua config
246  */
248 
249 } as_config;
250 
251 /******************************************************************************
252  * FUNCTIONS
253  *****************************************************************************/
254 
255 /**
256  * Initialize the configuration to default values.
257  *
258  * You should do this to ensure the configuration has valid values, before
259  * populating it with custom options.
260  *
261  * ~~~~~~~~~~{.c}
262  * as_config config;
263  * as_config_init(&config);
264  *
265  * config.hosts[0] = {.addr = "127.0.0.1", .port = 3000};
266  * ~~~~~~~~~~
267  *
268  * @param c The configuration to initialize.
269  *
270  * @return The initialized configuration on success. Otherwise NULL.
271  *
272  * @relates as_config
273  */
275