 |
All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
|
The as_config contains the settings for the aerospike client. Including default policies, seed hosts in the cluster and other settings.
Before using as_config, you must first initialize it. This will setup the default values.
Once initialized, you can populate the values.
The client will require at least one seed host defined in the configuration. The seed host is defined in as_config.hosts.
The client will iterate over the list until it connects with one of the hosts.
The configuration also defines default policies for the application. The as_config_init() function already presets default values for the policies.
Policies define the behavior of the client, which can be global across operations, global to a single operation, or local to a single use of an operation.
Each database operation accepts a policy for that operation as an a argument. This is considered a local policy, and is a single use policy. This policy supersedes any global policy defined.
If a value of the policy is not defined, then the rule is to fallback to the global policy for that operation. If the global policy for that operation is undefined, then the global default value will be used.
If you find that you have behavior that you want every use of an operation to utilize, then you can specify the default policy in as_config.policies.
For example, the aerospike_key_put() operation takes an as_policy_write policy. If you find yourself setting the key policy value for every call to aerospike_key_put(), then you may find it beneficial to set the global as_policy_write in as_policies.write, which all write operations will use.
Global operation policies:
If you are using user-defined functions (UDF) for processing query results (i.e aggregations), then you will find it useful to set the mod_lua settings. Of particular importance is the mod_lua.user_path, which allows you to define a path to where the client library will look for Lua files for processing.
Never call as_config_destroy() directly because ownership of config fields is transferred to aerospike in aerospike_init() or aerospike_new().
Definition at line 430 of file as_config.h.
#include "as_config.h"
Collaboration diagram for as_config:Data Fields | |
| uint32_t | async_max_conns_per_node |
| uint32_t | async_min_conns_per_node |
| as_auth_mode | auth_mode |
| char * | cluster_name |
| uint32_t | conn_pools_per_node |
| uint32_t | conn_timeout_ms |
| uint32_t | error_rate_window |
| as_cluster_event_callback | event_callback |
| void * | event_callback_udata |
| bool | fail_if_not_connected |
| as_vector * | hosts |
| as_addr_map * | ip_map |
| uint32_t | ip_map_size |
| uint32_t | login_timeout_ms |
| as_config_lua | lua |
| uint32_t | max_conns_per_node |
| uint32_t | max_error_rate |
| uint32_t | max_socket_idle |
| uint32_t | min_conns_per_node |
| char | password [AS_PASSWORD_SIZE] |
| uint32_t | pipe_max_conns_per_node |
| as_policies | policies |
| bool | rack_aware |
| int | rack_id |
| as_vector * | rack_ids |
| int | shm_key |
| uint32_t | shm_max_namespaces |
| uint32_t | shm_max_nodes |
| uint32_t | shm_takeover_threshold_sec |
| int | tend_thread_cpu |
| uint32_t | tender_interval |
| uint32_t | thread_pool_size |
| as_config_tls | tls |
| bool | use_services_alternate |
| bool | use_shm |
| char | user [AS_USER_SIZE] |
Related Functions | |
(Note that these are not member functions.) | |
| AS_EXTERN void | as_config_add_host (as_config *config, const char *address, uint16_t port) |
| AS_EXTERN bool | as_config_add_hosts (as_config *config, const char *string, uint16_t default_port) |
| AS_EXTERN void | as_config_add_rack_id (as_config *config, int rack_id) |
| AS_EXTERN void | as_config_clear_hosts (as_config *config) |
| AS_EXTERN as_config * | as_config_init (as_config *config) |
| static void | as_config_lua_init (as_config_lua *lua) |
| static void | as_config_set_cluster_event_callback (as_config *config, as_cluster_event_callback callback, void *udata) |
| static void | as_config_set_cluster_name (as_config *config, const char *cluster_name) |
| AS_EXTERN bool | as_config_set_user (as_config *config, const char *user, const char *password) |
| AS_EXTERN void | as_config_tls_add_host (as_config *config, const char *address, const char *tls_name, uint16_t port) |
| static void | as_config_tls_set_cafile (as_config *config, const char *cafile) |
| static void | as_config_tls_set_capath (as_config *config, const char *capath) |
| static void | as_config_tls_set_castring (as_config *config, const char *castring) |
| static void | as_config_tls_set_cert_blacklist (as_config *config, const char *cert_blacklist) |
| static void | as_config_tls_set_certfile (as_config *config, const char *certfile) |
| static void | as_config_tls_set_certstring (as_config *config, const char *certstring) |
| static void | as_config_tls_set_cipher_suite (as_config *config, const char *cipher_suite) |
| static void | as_config_tls_set_keyfile (as_config *config, const char *keyfile) |
| static void | as_config_tls_set_keyfile_pw (as_config *config, const char *pw) |
| static void | as_config_tls_set_keystring (as_config *config, const char *keystring) |
| static void | as_config_tls_set_protocols (as_config *config, const char *protocols) |
|
related |
Add host to seed the cluster. The host address will be copied. The caller is responsible for the original address string.
|
related |
Add seed host(s) from a string with format: hostname1[:tlsname1][:port1],... Hostname may also be an IP address in the following formats.
The host addresses will be copied. The caller is responsible for the original string.
Add rack id to list of server racks in order of preference. Only add racks that are close to the client rack. Do not add racks that are far away from the client. The client will still direct commands to far away racks if nodes on closer racks are not available.
rack_aware, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must also be set to enable this functionality.
Initialize the configuration to default values.
You should do this to ensure the configuration has valid values, before populating it with custom options.
|
related |
Initialize global lua configuration to defaults.
Definition at line 902 of file as_config.h.
References as_config_lua::cache_enabled, and as_config_lua::user_path.
|
related |
Set cluster event callback and user data.
Definition at line 890 of file as_config.h.
References event_callback, and event_callback_udata.
|
related |
Set expected cluster name.
Definition at line 879 of file as_config.h.
References as_config_set_string(), and cluster_name.
|
related |
User authentication for servers with restricted access. The password will be stored by the client and sent to server in hashed format.
|
related |
Add TLS host to seed the cluster. The host address and TLS name will be copied. The caller is responsible for the original address string.
|
related |
Set TLS path to a trusted CA certificate file.
Definition at line 914 of file as_config.h.
References as_config_set_string(), as_config_tls::cafile, and tls.
|
related |
Set TLS path to a directory of trusted certificates.
Definition at line 936 of file as_config.h.
References as_config_set_string(), as_config_tls::capath, and tls.
|
related |
Set string containing trusted CA certificate(s).
Definition at line 925 of file as_config.h.
References as_config_set_string(), as_config_tls::castring, and tls.
|
related |
Set TLS path to a certificate blacklist file.
Definition at line 969 of file as_config.h.
References as_config_set_string(), as_config_tls::cert_blacklist, and tls.
|
related |
Set TLS path to the client's certificate chain file for mutual authentication.
Definition at line 1013 of file as_config.h.
References as_config_set_string(), as_config_tls::certfile, and tls.
|
related |
Set client's certificate chain file string for mutual authentication.
Definition at line 1024 of file as_config.h.
References as_config_set_string(), as_config_tls::certstring, and tls.
|
related |
Set TLS enabled cipher suites.
Definition at line 958 of file as_config.h.
References as_config_set_string(), as_config_tls::cipher_suite, and tls.
|
related |
Set TLS path to the client's key for mutual authentication.
Definition at line 980 of file as_config.h.
References as_config_set_string(), as_config_tls::keyfile, and tls.
|
related |
Set decryption password for the client's key.
Definition at line 991 of file as_config.h.
References as_config_set_string(), as_config_tls::keyfile_pw, and tls.
|
related |
Set client's key string for mutual authentication.
Definition at line 1002 of file as_config.h.
References as_config_set_string(), as_config_tls::keystring, and tls.
|
related |
Set TLS enabled protocols.
Definition at line 947 of file as_config.h.
References as_config_set_string(), as_config_tls::protocols, and tls.
| uint32_t as_config::async_max_conns_per_node |
Maximum number of asynchronous (non-pipeline) connections allowed for each node. This limit will be enforced at the node/event loop level. If the value is 100 and 2 event loops are created, then each node/event loop asynchronous (non-pipeline) connection pool will have a limit of 50. Async transactions will be rejected if the limit would be exceeded. This variable is ignored if asynchronous event loops are not created.
Default: 100
Definition at line 538 of file as_config.h.
| uint32_t as_config::async_min_conns_per_node |
Minimum number of asynchronous connections allowed per server node. Preallocate min connections on client node creation. The client will periodically allocate new connections if count falls below min connections.
Server proto-fd-idle-ms and client max_socket_idle should be set to zero (no reap) if async_min_conns_per_node is greater than zero. Reaping connections can defeat the purpose of keeping connections in reserve for a future burst of activity.
Default: 0
Definition at line 527 of file as_config.h.
| as_auth_mode as_config::auth_mode |
Authentication mode. Default: AS_AUTH_INTERNAL
Definition at line 684 of file as_config.h.
| char* as_config::cluster_name |
Expected cluster name. If populated, the cluster_name must match the cluster-name field in the service section in each server configuration. This ensures that the specified seed nodes belong to the expected cluster on startup. If not, the client will refuse to add the node to the client's view of the cluster.
Default: NULL
Definition at line 455 of file as_config.h.
| uint32_t as_config::conn_pools_per_node |
Number of synchronous connection pools used for each node. Machines with 8 cpu cores or less usually need just one connection pool per node. Machines with a large number of cpu cores may have their synchronous performance limited by contention for pooled connections. Contention for pooled connections can be reduced by creating multiple mini connection pools per node.
Default: 1
Definition at line 560 of file as_config.h.
| uint32_t as_config::conn_timeout_ms |
Initial host connection timeout in milliseconds. The timeout when opening a connection to the server host for the first time. Default: 1000
Definition at line 567 of file as_config.h.
| uint32_t as_config::error_rate_window |
The number of cluster tend iterations that defines the window for max_error_rate. One tend iteration is defined as tender_interval plus the time to tend all nodes. At the end of the window, the error count is reset to zero and backoff state is removed on all nodes.
Default: 1
Definition at line 620 of file as_config.h.
| as_cluster_event_callback as_config::event_callback |
Cluster event function that will be called when nodes are added/removed from the cluster.
Default: NULL (no callback will be made)
Definition at line 462 of file as_config.h.
| void* as_config::event_callback_udata |
Cluster event user data that will be passed back to event_callback.
Default: NULL
Definition at line 469 of file as_config.h.
| bool as_config::fail_if_not_connected |
Should cluster instantiation fail if the client fails to connect to a seed or all the seed's peers.
If true, return an error if all seed connections fail or a seed is valid, but all peers from that seed are not reachable.
If false, a partial cluster will be created and the client will automatically connect to the remaining nodes when they become available.
Definition at line 696 of file as_config.h.
| as_vector* as_config::hosts |
Seed hosts. Populate with one or more hosts in the cluster that you intend to connect with. Do not set directly. Use as_config_add_hosts() or as_config_add_host() to add seed hosts.
Definition at line 435 of file as_config.h.
| as_addr_map* as_config::ip_map |
A IP translation table is used in cases where different clients use different server IP addresses. This may be necessary when using clients from both inside and outside a local area network. Default is no translation.
The key is the IP address returned from friend info requests to other servers. The value is the real IP address used to connect to the server.
A deep copy of ip_map is performed in aerospike_connect(). The caller is responsible for memory deallocation of the original data structure.
Definition at line 482 of file as_config.h.
| uint32_t as_config::ip_map_size |
Length of ip_map array. Default: 0
Definition at line 488 of file as_config.h.
| uint32_t as_config::login_timeout_ms |
Node login timeout in milliseconds. Default: 5000
Definition at line 573 of file as_config.h.
| as_config_lua as_config::lua |
lua config. This is a global config even though it's located here in cluster config. This config has been left here to avoid breaking the API.
The global lua config will only be changed once on first cluster initialization. A better method for initializing lua configuration is to leave this field alone and instead call aerospike_init_lua():
Definition at line 673 of file as_config.h.
| uint32_t as_config::max_conns_per_node |
Maximum number of synchronous connections allowed per server node. Synchronous transactions will go through retry logic and potentially fail with error code "AEROSPIKE_ERR_NO_MORE_CONNECTIONS" if the maximum number of connections would be exceeded.
The number of connections used per node depends on how many concurrent threads issue database commands plus sub-threads used for parallel multi-node commands (batch, scan, and query). One connection will be used for each thread.
Default: 100
Definition at line 514 of file as_config.h.
| uint32_t as_config::max_error_rate |
Maximum number of errors allowed per node per error_rate_window before backoff algorithm returns AEROSPIKE_MAX_ERROR_RATE for database commands to that node. If max_error_rate is zero, there is no error limit.
The counted error types are any error that causes the connection to close (socket errors and client timeouts), server device overload and server timeouts.
The application should backoff or reduce the transaction load until AEROSPIKE_MAX_ERROR_RATE stops being returned.
Default: 100
Definition at line 610 of file as_config.h.
| uint32_t as_config::max_socket_idle |
Maximum socket idle in seconds. Connection pools will discard sockets that have been idle longer than the maximum.
Connection pools are now implemented by a LIFO stack. Connections at the tail of the stack will always be the least used. These connections are checked for max_socket_idle once every 30 tend iterations (usually 30 seconds).
If server's proto-fd-idle-ms is greater than zero, then max_socket_idle should be at least a few seconds less than the server's proto-fd-idle-ms, so the client does not attempt to use a socket that has already been reaped by the server.
If server's proto-fd-idle-ms is zero (no reap), then max_socket_idle should also be zero. Connections retrieved from a pool in transactions will not be checked for max_socket_idle when max_socket_idle is zero. Idle connections will still be trimmed down from peak connections to min connections (min_conns_per_node and async_min_conns_per_node) using a hard-coded 55 second limit in the cluster tend thread.
Default: 0 seconds
Definition at line 595 of file as_config.h.
| uint32_t as_config::min_conns_per_node |
Minimum number of synchronous connections allowed per server node. Preallocate min connections on client node creation. The client will periodically allocate new connections if count falls below min connections.
Server proto-fd-idle-ms and client max_socket_idle should be set to zero (no reap) if min_conns_per_node is greater than zero. Reaping connections can defeat the purpose of keeping connections in reserve for a future burst of activity.
Default: 0
Definition at line 501 of file as_config.h.
| char as_config::password[AS_PASSWORD_SIZE] |
Password authentication to cluster. Leave empty for clusters running without restricted access.
Definition at line 445 of file as_config.h.
| uint32_t as_config::pipe_max_conns_per_node |
Maximum number of pipeline connections allowed for each node. This limit will be enforced at the node/event loop level. If the value is 100 and 2 event loops are created, then each node/event loop pipeline connection pool will have a limit of 50. Async transactions will be rejected if the limit would be exceeded. This variable is ignored if asynchronous event loops are not created.
Default: 64
Definition at line 549 of file as_config.h.
| as_policies as_config::policies |
Client policies
Definition at line 650 of file as_config.h.
| bool as_config::rack_aware |
Track server rack data. This field is useful when directing read commands to the server node that contains the key and exists on the same rack as the client. This serves to lower cloud provider costs when nodes are distributed across different racks/data centers.
rack_id or rack_ids, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must also be set to enable this functionality.
Default: false
Definition at line 715 of file as_config.h.
| int as_config::rack_id |
Rack where this client instance resides. If rack_ids is set, rack_id is ignored.
rack_aware, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must also be set to enable this functionality.
Default: 0
Definition at line 725 of file as_config.h.
| as_vector* as_config::rack_ids |
List of preferred racks in order of preference. If rack_ids is set, rack_id is ignored. Do not set directly. Use multiple as_config_add_rack_id() calls to add rack ids.
rack_aware, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must also be set to enable this functionality.
Default: NULL
Definition at line 736 of file as_config.h.
| int as_config::shm_key |
Identifier for the shared memory segment associated with the target Aerospike cluster. Each shared memory segment contains state for one Aerospike cluster. If there are multiple Aerospike clusters, a different shm_key must be defined for each cluster.
Default: 0xA9000000
Definition at line 757 of file as_config.h.
| uint32_t as_config::shm_max_namespaces |
Shared memory maximum number of namespaces allowed. This value is used to size the fixed shared memory segment. Leave a cushion between actual namespaces and shm_max_namespaces so new namespaces can be added without having to reboot the client. Default: 8
Definition at line 773 of file as_config.h.
| uint32_t as_config::shm_max_nodes |
Shared memory maximum number of server nodes allowed. This value is used to size the fixed shared memory segment. Leave a cushion between actual server node count and shm_max_nodes so new nodes can be added without having to reboot the client. Default: 16
Definition at line 765 of file as_config.h.
| uint32_t as_config::shm_takeover_threshold_sec |
Take over shared memory cluster tending if the cluster hasn't been tended by this threshold in seconds. Default: 30
Definition at line 780 of file as_config.h.
| int as_config::tend_thread_cpu |
Assign tend thread to this specific CPU ID. Default: -1 (Any CPU).
Definition at line 645 of file as_config.h.
| uint32_t as_config::tender_interval |
Polling interval in milliseconds for cluster tender Default: 1000
Definition at line 626 of file as_config.h.
| uint32_t as_config::thread_pool_size |
Number of threads stored in underlying thread pool used by synchronous batch/scan/query commands. These commands are often sent to multiple server nodes in parallel threads. A thread pool improves performance because threads do not have to be created/destroyed for each command. Calculate your value using the following formula:
thread_pool_size = (concurrent synchronous batch/scan/query commands) * (server nodes)
If your application only uses async commands, this field can be set to zero. Default: 16
Definition at line 639 of file as_config.h.
| as_config_tls as_config::tls |
TLS configuration parameters.
Definition at line 678 of file as_config.h.
| bool as_config::use_services_alternate |
Flag to signify if "services-alternate" should be used instead of "services" Default: false
Definition at line 702 of file as_config.h.
| bool as_config::use_shm |
Indicates if shared memory should be used for cluster tending. Shared memory is useful when operating in single threaded mode with multiple client processes. This model is used by wrapper languages such as PHP and Python. When enabled, the data partition maps are maintained by only one process and all other processes use these shared memory maps.
Shared memory should not be enabled for multi-threaded programs. Default: false
Definition at line 748 of file as_config.h.
| char as_config::user[AS_USER_SIZE] |
User authentication to cluster. Leave empty for clusters running without restricted access.
Definition at line 440 of file as_config.h.
