Detailed Description

The aerospike struct is used to connect and execute operations against an Aerospike database cluster.

Configuration

A client configuration is required to initialize an aerospike client. See as_config for details on configuration options.

At least one seed host must be defined.

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

Once connected to a host in the cluster, then client will gather information about the cluster, including all other nodes in the cluster. So, all that is needed is a single valid host. Multiple hosts can still be provided in case the first host is not currently active.

Initialization

Initialization requires a configuration to bind to the client instance.

The aerospike instance can be initialized via either:

aerospike_init() — Initialize a stack allocated aerospike instance.
aerospike_new() — Create and initialize a heap allocated aerospike instance.

Once initialized, the ownership of the as_config instance fields are transferred to the aerospike instance. The user should never call as_config_destroy() directly.

The following uses a stack allocated aerospike instance and initializes it with aerospike_init():

aerospike as;

aerospike_init(&as, &config);

aerospike

Definition aerospike.h:166

aerospike::aerospike_init

AS_EXTERN aerospike * aerospike_init(aerospike *as, as_config *config)

Connecting

The client will be connected if aerospike_connect() completes successfully:

if (aerospike_connect(&as, &err) != AEROSPIKE_OK) {
  fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
}

The err parameter will be populated if an error occurs. See as_error for more information on error handling.

An aerospike object internally keeps cluster state and maintains connection pools to the cluster. The same aerospike object should be reused by the application for database operations to a given cluster.

If the application requires connecting to multiple Aerospike clusters, the application must create multiple aerospike objects, each connecting to a different cluster.

Disconnecting

When the connection to the database is not longer required, then the connection to the cluster can be closed via aerospike_close():

aerospike_close(&as, &err);

aerospike::aerospike_close

AS_EXTERN as_status aerospike_close(aerospike *as, as_error *err)

Destruction

When the client is not longer required, the client and its resources should be releases via aerospike_destroy():

aerospike_destroy(&as);

aerospike::aerospike_destroy

AS_EXTERN void aerospike_destroy(aerospike *as)

Definition at line 166 of file aerospike.h.

#include "aerospike.h"

Collaboration diagram for aerospike:

Data Fields
as_config	config

Private Attributes
struct as_cluster_s *	cluster

Related Symbols
(Note that these are not member symbols.)
AS_EXTERN as_status	aerospike_abort (aerospike as, as_error err, as_txn txn, as_abort_status abort_status)

AS_EXTERN as_status	aerospike_abort_async (aerospike as, as_error err, as_txn txn, as_abort_listener listener, void udata, struct as_event_loop *event_loop)

AS_EXTERN as_status	aerospike_close (aerospike as, as_error err)

AS_EXTERN bool	aerospike_cluster_is_connected (aerospike *as)

AS_EXTERN as_status	aerospike_commit (aerospike as, as_error err, as_txn txn, as_commit_status commit_status)

AS_EXTERN as_status	aerospike_commit_async (aerospike as, as_error err, as_txn txn, as_commit_listener listener, void udata, struct as_event_loop *event_loop)

AS_EXTERN as_status	aerospike_connect (aerospike as, as_error err)

AS_EXTERN void	aerospike_destroy (aerospike *as)

AS_EXTERN aerospike *	aerospike_init (aerospike as, as_config config)

AS_EXTERN void	aerospike_init_lua (as_config_lua *config)

AS_EXTERN aerospike *	aerospike_new (as_config *config)

AS_EXTERN as_status	aerospike_reload_tls_config (aerospike as, as_error err)

AS_EXTERN as_status	aerospike_set_xdr_filter (aerospike as, as_error err, as_policy_info policy, const char dc, const char ns, const char filter_b64)

AS_EXTERN void	aerospike_stop_on_interrupt (bool stop)

AS_EXTERN as_status	aerospike_truncate (aerospike as, as_error err, as_policy_info policy, const char ns, const char *set, uint64_t before_nanos)

typedef void(*	as_abort_listener) (as_error err, as_abort_status status, void udata, struct as_event_loop *event_loop)

typedef void(*	as_commit_listener) (as_error err, as_commit_status status, void udata, struct as_event_loop *event_loop)

Friends And Related Symbol Documentation

◆ aerospike_abort()

AS_EXTERN as_status aerospike_abort	(	aerospike *	as,
		as_error *	err,
		as_txn *	txn,
		as_abort_status *	abort_status )

Requires server version 8.0+

Parameters

as	Aerospike instance.
err	Error detail structure that is populated if an error occurs.
txn	Transaction.
abort_status	Indicates success or the step in the abort process that failed. Pass in NULL to ignore.

Returns: AEROSPIKE_OK if successful. Otherwise an error.

◆ aerospike_abort_async()

AS_EXTERN as_status aerospike_abort_async	(	aerospike *	as,
		as_error *	err,
		as_txn *	txn,
		as_abort_listener	listener,
		void *	udata,
		struct as_event_loop *	event_loop )

Requires server version 8.0+

Parameters

as	Aerospike instance.
err	Error detail structure that is populated if an error occurs.
txn	Transaction.
listener	User function to be called with command results.
udata	User data that is forwarded from asynchronous command function.
event_loop	Event loop that this command was executed on. Use this event loop when running nested asynchronous commands when single threaded behavior is desired for the group of commands.

Returns: AEROSPIKE_OK if async command succesfully queued. Otherwise an error.

◆ aerospike_close()

AS_EXTERN as_status aerospike_close	(	aerospike *	as,
		as_error *	err )

aerospike_close(&as, &err);

Parameters

as	The aerospike instance to disconnect from a cluster.
err	If an error occurs, the err will be populated.

Returns: AEROSPIKE_OK on success. Otherwise an error occurred.

◆ aerospike_cluster_is_connected()

AS_EXTERN bool aerospike_cluster_is_connected ( aerospike * as )

bool connected = aerospike_cluster_is_connected(&as);

aerospike::aerospike_cluster_is_connected

AS_EXTERN bool aerospike_cluster_is_connected(aerospike *as)

Parameters

as	The aerospike instance to check.

Returns: true when cluster is connected.

◆ aerospike_commit()

AS_EXTERN as_status aerospike_commit	(	aerospike *	as,
		as_error *	err,
		as_txn *	txn,
		as_commit_status *	commit_status )

Attempt to commit the given transaction. First, the expected record versions are sent to the server nodes for verification. If all nodes return success, the transaction is committed. Otherwise, the transaction is aborted.

Requires server version 8.0+

Parameters

as	Aerospike instance.
err	Error detail structure that is populated if an error occurs.
txn	Transaction.
commit_status	Indicates success or the step in the commit process that failed. Pass in NULL to ignore.

Returns: AEROSPIKE_OK if successful. Otherwise an error.

◆ aerospike_commit_async()

AS_EXTERN as_status aerospike_commit_async	(	aerospike *	as,
		as_error *	err,
		as_txn *	txn,
		as_commit_listener	listener,
		void *	udata,
		struct as_event_loop *	event_loop )

Asynchronously attempt to commit the given transaction. First, the expected record versions are sent to the server nodes for verification. If all nodes return success, the transaction is committed. Otherwise, the transaction is aborted.

Requires server version 8.0+

Parameters

as	Aerospike instance.
err	Error detail structure that is populated if an error occurs.
txn	Transaction.
listener	User function to be called with command results.
udata	User data that is forwarded from asynchronous command function.
event_loop	Event loop that this command was executed on. Use this event loop when running nested asynchronous commands when single threaded behavior is desired for the group of commands.

Returns: AEROSPIKE_OK if async command succesfully queued. Otherwise an error.

◆ aerospike_connect()

AS_EXTERN as_status aerospike_connect	(	aerospike *	as,
		as_error *	err )

aerospike_connect(&as, &err);

Once you are finished using the connection, then you must close it via the aerospike_close() function.

If connect fails, then you do not need to call aerospike_close().

Parameters

as	The aerospike instance to connect to a cluster.
err	If an error occurs, the err will be populated.

Returns: AEROSPIKE_OK on success. Otherwise an error occurred.

◆ aerospike_destroy()

AS_EXTERN void aerospike_destroy ( aerospike * as )

aerospike_destroy(&as);

Parameters

as	The aerospike instance to destroy

◆ aerospike_init()

AS_EXTERN aerospike * aerospike_init	(	aerospike *	as,
		as_config *	config )

The config parameter can be an instance of as_config or NULL. If NULL, then the default configuration will be used.

Ownership of the as_config instance fields are transferred to the aerospike instance. The user should never call as_config_destroy() directly.

aerospike as;

aerospike_init(&as, &config);

Once you are finished using the instance, then you should destroy it via the aerospike_destroy() function.

Parameters

as	The aerospike instance to initialize.
config	The configuration to use for the instance.

Returns: the initialized aerospike instance

See also: config for information on configuring the client.

◆ aerospike_init_lua()

AS_EXTERN void aerospike_init_lua ( as_config_lua * config )

Parameters

config The lua configuration to use for all cluster instances.

◆ aerospike_new()

AS_EXTERN aerospike * aerospike_new ( as_config * config )

Ownership of the as_config instance fields are transferred to the aerospike instance. The user should never call as_config_destroy() directly.

aerospike* as = aerospike_new(&config);

aerospike::aerospike_new

AS_EXTERN aerospike * aerospike_new(as_config *config)

Once you are finished using the instance, then you should destroy it via the aerospike_destroy() function.

Parameters

config The configuration to use for the instance.

Returns: a new aerospike instance

See also: config for information on configuring the client.

◆ aerospike_reload_tls_config()

AS_EXTERN as_status aerospike_reload_tls_config	(	aerospike *	as,
		as_error *	err )

Parameters

as	Aerospike instance whose TLS configuration to refresh.
err	If an error occurs, this will be populated.

Returns: AEROSPIKE_OK on success. Otherwise an error occurred.

◆ aerospike_set_xdr_filter()

AS_EXTERN as_status aerospike_set_xdr_filter	(	aerospike *	as,
		as_error *	err,
		as_policy_info *	policy,
		const char *	dc,
		const char *	ns,
		const char *	filter_b64 )

Parameters

as	Aerospike instance.
err	If an error occurs, this will be populated.
policy	Info policy. If NULL, then the default policy will be used.
dc	Datacenter name.
ns	Namespace.
filter_b64	expression filter in base64 encoding. Use as_exp_build_b64() to create.

Returns: AEROSPIKE_OK on success. Otherwise an error occurred.

◆ aerospike_stop_on_interrupt()

AS_EXTERN void aerospike_stop_on_interrupt ( bool stop )

◆ aerospike_truncate()

AS_EXTERN as_status aerospike_truncate	(	aerospike *	as,
		as_error *	err,
		as_policy_info *	policy,
		const char *	ns,
		const char *	set,
		uint64_t	before_nanos )

See https://www.aerospike.com/docs/reference/info#truncate

This asynchronous server call may return before the truncation is complete. The user can still write new records after the server returns because new records will have last update times greater than the truncate cutoff (set at the time of truncate call).

Parameters

as	Aerospike instance.
err	If an error occurs, the err will be populated.
policy	Info policy. If NULL, then the default policy will be used.
ns	Required namespace.
set	Optional set name. Pass in NULL to delete all sets in namespace.
before_nanos	Optionally delete records before record last update time. Units are in nanoseconds since unix epoch (1970-01-01). If specified, value must be before the current time. Pass in 0 to delete all records in namespace/set regardless of last update time.

Returns: AEROSPIKE_OK on success. Otherwise an error occurred.

◆ as_abort_listener

typedef void(* as_abort_listener) (as_error *err, as_abort_status status, void *udata, struct as_event_loop *event_loop)

Parameters

err	Error structure that is populated if an error occurs. NULL on success.
status	Status of abort when err is NULL.
udata	User data that is forwarded from asynchronous command function.
event_loop	Event loop that this command was executed on. Use this event loop when running nested asynchronous commands when single threaded behavior is desired for the group of commands.

Definition at line 133 of file aerospike_txn.h.

◆ as_commit_listener

typedef void(* as_commit_listener) (as_error *err, as_commit_status status, void *udata, struct as_event_loop *event_loop)

Parameters

err	Error structure that is populated if an error occurs. NULL on success.
status	Status of commit when err is NULL.
udata	User data that is forwarded from asynchronous command function.
event_loop	Event loop that this command was executed on. Use this event loop when running nested asynchronous commands when single threaded behavior is desired for the group of commands.

Definition at line 86 of file aerospike_txn.h.

Field Documentation

◆ cluster

struct as_cluster_s* aerospike::cluster

private

Cluster state.

Definition at line 172 of file aerospike.h.

◆ config

as_config aerospike::config

Client configuration.

Definition at line 177 of file aerospike.h.

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

Detailed Description

Configuration

Initialization

Connecting

Disconnecting

Destruction

Data Fields

Private Attributes

Related Symbols

Friends And Related Symbol Documentation

◆ aerospike_abort()

◆ aerospike_abort_async()

◆ aerospike_close()

◆ aerospike_cluster_is_connected()

◆ aerospike_commit()

◆ aerospike_commit_async()

◆ aerospike_connect()

◆ aerospike_destroy()

◆ aerospike_init()

◆ aerospike_init_lua()

◆ aerospike_new()

◆ aerospike_reload_tls_config()

◆ aerospike_set_xdr_filter()

◆ aerospike_stop_on_interrupt()

◆ aerospike_truncate()

◆ as_abort_listener

◆ as_commit_listener

Field Documentation

◆ cluster

◆ config