Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
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
91
}
as_config_host
;
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
*/
123
bool
cache_enabled
;
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
*/
266
as_addr_map
*
ip_map
;
267
268
/**
269
* Length of ip_map array.
270
* Default: 0
271
*/
272
uint32_t
ip_map_size
;
273
274
/**
275
* Maximum number of synchronous connections allowed per server node. Synchronous transactions
276
* will go through retry logic and potentially fail with error code "AEROSPIKE_ERR_NO_MORE_CONNECTIONS"
277
* if the maximum number of connections would be exceeded.
278
*
279
* The number of connections used per node depends on how many concurrent threads issue
280
* database commands plus sub-threads used for parallel multi-node commands (batch, scan,
281
* and query). One connection will be used for each thread.
282
*
283
* Default: 300
284
*/
285
uint32_t
max_conns_per_node
;
286
287
/**
288
* Maximum number of asynchronous (non-pipeline) connections allowed for each node.
289
* This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
290
* loops are created, then each node/event loop asynchronous (non-pipeline) connection pool
291
* will have a limit of 50. Async transactions will be rejected if the limit would be exceeded.
292
* This variable is ignored if asynchronous event loops are not created.
293
* Default: 300
294
*/
295
uint32_t
async_max_conns_per_node
;
296
297
/**
298
* Maximum number of pipeline connections allowed for each node.
299
* This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
300
* loops are created, then each node/event loop pipeline connection pool will have a limit of 50.
301
* Async transactions will be rejected if the limit would be exceeded.
302
* This variable is ignored if asynchronous event loops are not created.
303
* Default: 64
304
*/
305
uint32_t
pipe_max_conns_per_node
;
306
307
/**
308
* Initial host connection timeout in milliseconds. The timeout when opening a connection
309
* to the server host for the first time.
310
* Default: 1000
311
*/
312
uint32_t
conn_timeout_ms
;
313
314
/**
315
* Polling interval in milliseconds for cluster tender
316
* Default: 1000
317
*/
318
uint32_t
tender_interval
;
319
320
/**
321
* Number of threads stored in underlying thread pool that is used in batch/scan/query commands.
322
* These commands are often sent to multiple server nodes in parallel threads. A thread pool
323
* improves performance because threads do not have to be created/destroyed for each command.
324
* Calculate your value using the following formula:
325
*
326
* thread_pool_size = (concurrent batch/scan/query commands) * (server nodes)
327
*
328
* Default: 16
329
*/
330
uint32_t
thread_pool_size
;
331
332
/**
333
* Count of entries in hosts array.
334
*/
335
uint32_t
hosts_size
;
336
337
/**
338
* (seed) hosts
339
* Populate with one or more hosts in the cluster
340
* that you intend to connect with.
341
*/
342
as_config_host
hosts[
AS_CONFIG_HOSTS_SIZE
];
343
344
/**
345
* Client policies
346
*/
347
as_policies
policies
;
348
349
/**
350
* lua config. This is a global config even though it's located here in cluster config.
351
* This config has been left here to avoid breaking the API.
352
*
353
* The global lua config will only be changed once on first cluster initialization.
354
* A better method for initializing lua configuration is to leave this field alone and
355
* instead call aerospike_init_lua():
356
*
357
* ~~~~~~~~~~{.c}
358
* // Get default global lua configuration.
359
* as_config_lua lua;
360
* as_config_lua_init(&lua);
361
*
362
* // Optionally modify lua defaults.
363
* lua.cache_enabled = <enable lua cache>;
364
* strcpy(lua.system_path, <lua system directory>);
365
* strcpy(lua.user_path, <lua user directory>);
366
*
367
* // Initialize global lua configuration.
368
* aerospike_init_lua(&lua);
369
* ~~~~~~~~~~
370
*/
371
as_config_lua
lua
;
372
373
/**
374
* Action to perform if client fails to connect to seed hosts.
375
*
376
* If fail_if_not_connected is true (default), the cluster creation will fail
377
* when all seed hosts are not reachable.
378
*
379
* If fail_if_not_connected is false, an empty cluster will be created and the
380
* client will automatically connect when Aerospike server becomes available.
381
*/
382
bool
fail_if_not_connected
;
383
384
/**
385
* Flag to signify if "services-alternate" should be used instead of "services"
386
* Default : false
387
*/
388
bool
use_services_alternate
;
389
390
/**
391
* Indicates if shared memory should be used for cluster tending. Shared memory
392
* is useful when operating in single threaded mode with multiple client processes.
393
* This model is used by wrapper languages such as PHP and Python. When enabled,
394
* the data partition maps are maintained by only one process and all other processes
395
* use these shared memory maps.
396
*
397
* Shared memory should not be enabled for multi-threaded programs.
398
* Default: false
399
*/
400
bool
use_shm
;
401
402
/**
403
* Shared memory identifier. This identifier should be the same for all applications
404
* that use the Aerospike C client.
405
* Default: 0xA5000000
406
*/
407
int
shm_key
;
408
409
/**
410
* Shared memory maximum number of server nodes allowed. This value is used to size
411
* the fixed shared memory segment. Leave a cushion between actual server node
412
* count and shm_max_nodes so new nodes can be added without having to reboot the client.
413
* Default: 16
414
*/
415
uint32_t
shm_max_nodes
;
416
417
/**
418
* Shared memory maximum number of namespaces allowed. This value is used to size
419
* the fixed shared memory segment. Leave a cushion between actual namespaces
420
* and shm_max_namespaces so new namespaces can be added without having to reboot the client.
421
* Default: 8
422
*/
423
uint32_t
shm_max_namespaces
;
424
425
/**
426
* Take over shared memory cluster tending if the cluster hasn't been tended by this
427
* threshold in seconds.
428
* Default: 30
429
*/
430
uint32_t
shm_takeover_threshold_sec
;
431
}
as_config
;
432
433
/******************************************************************************
434
* FUNCTIONS
435
*****************************************************************************/
436
437
/**
438
* Initialize the configuration to default values.
439
*
440
* You should do this to ensure the configuration has valid values, before
441
* populating it with custom options.
442
*
443
* ~~~~~~~~~~{.c}
444
* as_config config;
445
* as_config_init(&config);
446
* as_config_add_host(&config, "127.0.0.1", 3000);
447
* ~~~~~~~~~~
448
*
449
* @param c The configuration to initialize.
450
*
451
* @return The initialized configuration on success. Otherwise NULL.
452
*
453
* @relates as_config
454
*/
455
as_config
*
as_config_init
(
as_config
* c);
456
457
/**
458
* Add host to seed the cluster.
459
*
460
* ~~~~~~~~~~{.c}
461
* as_config config;
462
* as_config_init(&config);
463
* as_config_add_host(&config, "127.0.0.1", 3000);
464
* ~~~~~~~~~~
465
*
466
* @relates as_config
467
*/
468
static
inline
void
469
as_config_add_host
(
as_config
* config,
const
char
* addr, uint16_t port)
470
{
471
as_config_host
* host = &config->
hosts
[config->
hosts_size
++];
472
host->
addr
= addr;
473
host->
port
= port;
474
}
475
476
/**
477
* User authentication for servers with restricted access. The password will be stored by the
478
* client and sent to server in hashed format.
479
*
480
* ~~~~~~~~~~{.c}
481
* as_config config;
482
* as_config_init(&config);
483
* as_config_set_user(&config, "charlie", "mypassword");
484
* ~~~~~~~~~~
485
*
486
* @relates as_config
487
*/
488
bool
489
as_config_set_user
(
as_config
* config,
const
char
* user,
const
char
* password);
490
491
/**
492
* Initialize global lua configuration to defaults.
493
*/
494
static
inline
void
495
as_config_lua_init
(
as_config_lua
* lua)
496
{
497
lua->
cache_enabled
=
false
;
498
strcpy(lua->
system_path
, AS_CONFIG_LUA_SYSTEM_PATH);
499
strcpy(lua->
user_path
, AS_CONFIG_LUA_USER_PATH);
500
}
501
502
#ifdef __cplusplus
503
}
// end extern "C"
504
#endif