The future result of an operation.

It can represent a result if the operation completed successfully or an error if the operation failed. It can be waited on, polled or a callback can be attached.

Functions

void

cass_future_free

( CassFuture * future )

Frees a future instance. A future can be freed anytime.

Parameters:
Name Type Details
future CassFuture *
CassError

cass_future_set_callback

( CassFuture * future, CassFutureCallback callback, void * data )

Sets a callback that is called when a future is set

Parameters:
Name Type Details
in future CassFuture *
in callback CassFutureCallback
in data void *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

cass_bool_t

cass_future_ready

( CassFuture * future )

Gets the set status of the future.

Parameters:
Name Type Details
in future CassFuture *
Returns:
Type Details
cass_bool_t

true if set

void

cass_future_wait

( CassFuture * future )

Wait for the future to be set with either a result or error.

Important: Do not wait in a future callback. Waiting in a future callback will cause a deadlock.

Parameters:
Name Type Details
in future CassFuture *
cass_bool_t

cass_future_wait_timed

( CassFuture * future, cass_duration_t timeout_us )

Wait for the future to be set or timeout.

Parameters:
Name Type Details
in future CassFuture *
in timeout_us cass_duration_t

wait time in microseconds

Returns:
Type Details
cass_bool_t

false if returned due to timeout

const CassResult *

cass_future_get_result

( CassFuture * future )

Gets the result of a successful future. If the future is not ready this method will wait for the future to be set.

Parameters:
Name Type Details
in future CassFuture *
Returns:
Type Details
const CassResult *

CassResult instance if successful, otherwise NULL for error. The return instance must be freed using CassResult::cass_result_free.

See Also:
const CassErrorResult *

cass_future_get_error_result

( CassFuture * future )

Gets the error result from a future that failed as a result of a server error. If the future is not ready this method will wait for the future to be set.

Parameters:
Name Type Details
in future CassFuture *
Returns:
Type Details
const CassErrorResult *

CassErrorResult instance if the request failed with a server error, otherwise NULL if the request was successful or the failure was not caused by a server error. The return instance must be freed using CassErrorResult::cass_error_result_free.

See Also:
const CassPrepared *

cass_future_get_prepared

( CassFuture * future )

Gets the result of a successful future. If the future is not ready this method will wait for the future to be set. The first successful call consumes the future, all subsequent calls will return NULL.

Parameters:
Name Type Details
in future CassFuture *
Returns:
Type Details
const CassPrepared *

CassPrepared instance if successful, otherwise NULL for error. The return instance must be freed using CassPrepared::cass_prepared_free.

See Also:
CassError

cass_future_error_code

( CassFuture * future )

Gets the error code from future. If the future is not ready this method will wait for the future to be set.

Parameters:
Name Type Details
in future CassFuture *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

See Also:
void

cass_future_error_message

( CassFuture * future, const char ** message, size_t * message_length )

Gets the error message from future. If the future is not ready this method will wait for the future to be set.

Parameters:
Name Type Details
in future CassFuture *
out message const char **

Empty string returned if successful, otherwise a message describing the error is returned.

out message_length size_t *
size_t

cass_future_custom_payload_item_count

( CassFuture * future )

Gets a the number of custom payload items from a response future. If the future is not ready this method will wait for the future to be set.

Requires Cassandra: 2.2+

Parameters:
Name Type Details
in future CassFuture *
Returns:
Type Details
size_t

the number of custom payload items.

CassError

cass_future_custom_payload_item

( CassFuture * future, size_t index, const char ** name, size_t * name_length, const cass_byte_t ** value, size_t * value_size )

Gets a custom payload item from a response future at the specified index. If the future is not ready this method will wait for the future to be set.

Requires Cassandra: 2.2+

Parameters:
Name Type Details
in future CassFuture *
in index size_t
out name const char **
out name_length size_t *
out value const cass_byte_t **
out value_size size_t *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.