All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Data Fields | Related Functions
as_config Struct Reference

Detailed Description

The as_config contains the settings for the aerospike client. Including default policies, seed hosts in the cluster and other settings.

Initialization

Before using as_config, you must first initialize it. This will setup the default values.

as_config config;
as_config_init(&config);

Once initialized, you can populate the values.

Seed Hosts

The client will require at least one seed host defined in the configuration. The seed host is defined in as_config.hosts.

as_config_add_host(&config, "127.0.0.1", 3000);

The client will iterate over the list until it connects with one of the hosts.

Policies

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.

If you find that you want to use a policy value across all operations, then you may find it beneficial to set the default policy value for that policy value.

For example, if you keep setting the key policy value to AS_POLICY_KEY_SEND, then you may want to just set as_policies.key. This will set the global default value for the policy value. So, if an global operation policy or a local operation policy does not define a value, then this value will be used.

Global default policy values:

Global operation policies:

User-Defined Function Settings

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.

strcpy(config.mod_lua.user_path, "/home/me/lua");

Never call as_config_destroy() directly because ownership of config fields is transferred to aerospike in aerospike_init() or aerospike_new().

Definition at line 396 of file as_config.h.

#include "as_config.h"

+ Collaboration diagram for as_config:

Data Fields

uint32_t async_max_conns_per_node
 
char * cluster_name
 
uint32_t conn_pools_per_node
 
uint32_t conn_timeout_ms
 
as_cluster_event_callback event_callback
 
void * event_callback_udata
 
bool fail_if_not_connected
 
as_vectorhosts
 
as_addr_mapip_map
 
uint32_t ip_map_size
 
as_config_lua lua
 
uint32_t max_conns_per_node
 
uint32_t max_socket_idle
 
char password [AS_PASSWORD_HASH_SIZE]
 
uint32_t pipe_max_conns_per_node
 
as_policies policies
 
int shm_key
 
uint32_t shm_max_namespaces
 
uint32_t shm_max_nodes
 
uint32_t shm_takeover_threshold_sec
 
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.)

void as_config_add_host (as_config *config, const char *address, uint16_t port)
 
bool as_config_add_hosts (as_config *config, const char *string, uint16_t default_port)
 
void as_config_clear_hosts (as_config *config)
 
as_configas_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)
 
bool as_config_set_user (as_config *config, const char *user, const char *password)
 
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_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_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_protocols (as_config *config, const char *protocols)
 

Friends And Related Function Documentation

void as_config_add_host ( as_config config,
const char *  address,
uint16_t  port 
)
related

Add host to seed the cluster. The host address will be copied. The caller is responsible for the original address string.

as_config config;
as_config_init(&config);
as_config_add_host(&config, "127.0.0.1", 3000);
bool as_config_add_hosts ( as_config config,
const char *  string,
uint16_t  default_port 
)
related

Add seed host(s) from a string with format: hostname1[:tlsname1][:port1],... Hostname may also be an IP address in the following formats.

IPv4: xxx.xxx.xxx.xxx
IPv6: [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
IPv6: [xxxx::xxxx]

The host addresses will be copied. The caller is responsible for the original string.

as_config config;
as_config_init(&config);
as_config_add_hosts(&config, "host1,host2:3010,192.168.20.1:3020,[2001::1000]:3030", 3000);
void as_config_clear_hosts ( as_config config)
related

Remove all hosts.

as_config * as_config_init ( as_config config)
related

Initialize the configuration to default values.

You should do this to ensure the configuration has valid values, before populating it with custom options.

as_config config;
as_config_init(&config);
as_config_add_host(&config, "127.0.0.1", 3000);
static void as_config_lua_init ( as_config_lua lua)
related

Initialize global lua configuration to defaults.

Definition at line 752 of file as_config.h.

References as_config_lua::cache_enabled, as_config_lua::system_path, and as_config_lua::user_path.

static void as_config_set_cluster_event_callback ( as_config config,
as_cluster_event_callback  callback,
void *  udata 
)
related

Set cluster event callback and user data.

Definition at line 740 of file as_config.h.

References event_callback, and event_callback_udata.

static void as_config_set_cluster_name ( as_config config,
const char *  cluster_name 
)
related

Set expected cluster name.

Definition at line 729 of file as_config.h.

References as_config_set_string(), and cluster_name.

bool as_config_set_user ( as_config config,
const char *  user,
const char *  password 
)
related

User authentication for servers with restricted access. The password will be stored by the client and sent to server in hashed format.

as_config config;
as_config_init(&config);
as_config_set_user(&config, "charlie", "mypassword");
void as_config_tls_add_host ( as_config config,
const char *  address,
const char *  tls_name,
uint16_t  port 
)
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.

as_config config;
as_config_init(&config);
as_config_tls_add_host(&config, "127.0.0.1", "node1.test.org", 3000);
static void as_config_tls_set_cafile ( as_config config,
const char *  cafile 
)
related

Set TLS path to a trusted CA certificate file.

Definition at line 765 of file as_config.h.

References as_config_set_string(), as_config_tls::cafile, and tls.

static void as_config_tls_set_capath ( as_config config,
const char *  capath 
)
related

Set TLS path to a directory of trusted certificates.

Definition at line 776 of file as_config.h.

References as_config_set_string(), as_config_tls::capath, and tls.

static void as_config_tls_set_cert_blacklist ( as_config config,
const char *  cert_blacklist 
)
related

Set TLS path to a certificate blacklist file.

Definition at line 809 of file as_config.h.

References as_config_set_string(), as_config_tls::cert_blacklist, and tls.

static void as_config_tls_set_certfile ( as_config config,
const char *  certfile 
)
related

Set TLS path to the client's certificate chain file for mutual authentication.

Definition at line 831 of file as_config.h.

References as_config_set_string(), as_config_tls::certfile, and tls.

static void as_config_tls_set_cipher_suite ( as_config config,
const char *  cipher_suite 
)
related

Set TLS enabled cipher suites.

Definition at line 798 of file as_config.h.

References as_config_set_string(), as_config_tls::cipher_suite, and tls.

static void as_config_tls_set_keyfile ( as_config config,
const char *  keyfile 
)
related

Set TLS path to the client's key for mutual authentication.

Definition at line 820 of file as_config.h.

References as_config_set_string(), as_config_tls::keyfile, and tls.

static void as_config_tls_set_protocols ( as_config config,
const char *  protocols 
)
related

Set TLS enabled protocols.

Definition at line 787 of file as_config.h.

References as_config_set_string(), as_config_tls::protocols, and tls.

Field Documentation

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: 300

Definition at line 476 of file as_config.h.

char* as_config::cluster_name

Expected cluster name. If not null, server nodes must return this cluster name in order to join the client's view of the cluster. Should only be set when connecting to servers that support the "cluster-name" info command. Use as_config_set_cluster_name() to set this field. Default: NULL

Definition at line 420 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 497 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 504 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 427 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 434 of file as_config.h.

bool as_config::fail_if_not_connected

Action to perform if client fails to connect to seed hosts.

If fail_if_not_connected is true (default), the cluster creation will fail when all seed hosts are not reachable.

If fail_if_not_connected is false, an empty cluster will be created and the client will automatically connect when Aerospike server becomes available.

Definition at line 580 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 401 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 447 of file as_config.h.

uint32_t as_config::ip_map_size

Length of ip_map array. Default: 0

Definition at line 453 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():

// Get default global lua configuration.
// Optionally modify lua defaults.
lua.cache_enabled = <enable lua cache>;
strcpy(lua.system_path, <lua system directory>);
strcpy(lua.user_path, <lua user directory>);
// Initialize global lua configuration.

Definition at line 564 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: 300

Definition at line 466 of file as_config.h.

uint32_t as_config::max_socket_idle

Maximum socket idle time in seconds. Connection pools will discard sockets that have been idle longer than the maximum. The value is limited to 24 hours (86400).

It's important to set this value to a few seconds less than the server's proto-fd-idle-ms (default 60000 milliseconds or 1 minute), so the client does not attempt to use a socket that has already been reaped by the server.

Default: 0 seconds (disabled) for non-TLS connections, 55 seconds for TLS connections.

Definition at line 516 of file as_config.h.

char as_config::password[AS_PASSWORD_HASH_SIZE]

Password authentication to cluster. The hashed value of password will be stored by the client and sent to server in same format. Leave empty for clusters running without restricted access.

Definition at line 412 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 486 of file as_config.h.

as_policies as_config::policies

Client policies

Definition at line 540 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: 0xA7000000

Definition at line 607 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 623 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 615 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 630 of file as_config.h.

uint32_t as_config::tender_interval

Polling interval in milliseconds for cluster tender Default: 1000

Definition at line 522 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 535 of file as_config.h.

as_config_tls as_config::tls

Definition at line 569 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 586 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 598 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 406 of file as_config.h.


The documentation for this struct was generated from the following file: