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