CassFuture¶

struct CassFuture¶

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.

Public Functions

void cass_future_free(CassFuture *future)¶

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

CassError cass_future_set_callback(CassFuture *future, CassFutureCallback callback, void *data)¶

Sets a callback that is called when a future is set

Parameters:

• future – [in]

• callback – [in]

• data – [in]

Returns:

CASS_OK if successful, otherwise an error occurred

cass_bool_t cass_future_ready(CassFuture *future)¶

Gets the set status of the future.

Parameters:

future – [in]

Returns:

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:

future – [in]

cass_bool_t cass_future_wait_timed(CassFuture *future, cass_duration_t timeout_us)¶

Wait for the future to be set or timeout.

Parameters:

• future – [in]

• timeout_us – [in] wait time in microseconds

Returns:

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.

See also

cass_session_execute() and cass_session_execute_batch()

Parameters:

future – [in]

Returns:

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

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.

See also

cass_session_execute() and cass_session_execute_batch()

Parameters:

future – [in]

Returns:

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 cass_error_result_free().

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.

See also

cass_session_prepare()

Parameters:

future – [in]

Returns:

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

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.

See also

cass_error_desc()

Parameters:

future – [in]

Returns:

CASS_OK if successful, otherwise an error occurred.

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:

• future – [in]

• message – [out] Empty string returned if successful, otherwise a message describing the error is returned.

• message_length – [out]

CassError cass_future_tracing_id(CassFuture *future, CassUuid *tracing_id)¶

Gets the tracing ID associated with the request.

Parameters:

• future – [in]

• tracing_id – [out]

Returns:

CASS_OK if successful, otherwise an error occurred.

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 Apache Cassandra: 2.2+

Parameters:

future – [in]

Returns:

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 Apache Cassandra: 2.2+

Parameters:

• future – [in]

• index – [in]

• name – [out]

• name_length – [out]

• value – [out]

• value_size – [out]

Returns:

CASS_OK if successful, otherwise an error occurred.

const CassNode *cass_future_coordinator(CassFuture *future)¶

Gets the node that acted as coordinator for this query. If the future is not ready this method will wait for the future to be set.

See also

cass_statement_set_node()

Parameters:

future –

Returns:

The coordinator node that handled the query. The lifetime of this object is the same as the result object it came from. NULL can be returned if the future is not a response future or if an error occurs before a coordinator responds.