CassSession¶

struct CassSession¶

A session object is used to execute queries and maintains cluster state through the control connection. The control connection is used to auto-discover nodes and monitor cluster changes (topology and schema). Each session also maintains multiple pools of connections to cluster nodes which are used to query the cluster.

Instances of the session object are thread-safe to execute queries.

Public Functions

CassSession *cass_session_new()¶

Creates a new session.

See also

cass_session_free()

Returns:

Returns a session that must be freed.

void cass_session_free(CassSession *session)¶

Frees a session instance. If the session is still connected it will be synchronously closed before being deallocated.

Important: Do not free a session in a future callback. Freeing a session in a future callback will cause a deadlock.

Parameters:

session – [in]

CassFuture *cass_session_connect(CassSession *session, const CassCluster *cluster)¶

Connects a session.

See also

cass_session_close()

Parameters:

• session – [in]

• cluster – [in] The cluster configuration is copied into the session and is immutable after connection.

Returns:

A future that must be freed.

CassFuture *cass_session_connect_keyspace(CassSession *session, const CassCluster *cluster, const char *keyspace)¶

Connects a session and sets the keyspace.

See also

cass_session_close()

Parameters:

• session – [in]

• cluster – [in] The cluster configuration is copied into the session and is immutable after connection.

• keyspace – [in]

Returns:

A future that must be freed.

CassFuture *cass_session_connect_keyspace_n(CassSession *session, const CassCluster *cluster, const char *keyspace, size_t keyspace_length)¶

Same as cass_session_connect_keyspace(), but with lengths for string parameters.

See also

cass_session_connect_keyspace()

Parameters:

• session – [in]

• cluster – [in]

• keyspace – [in]

• keyspace_length – [in]

Returns:

same as cass_session_connect_keyspace()

CassFuture *cass_session_close(CassSession *session)¶

Closes the session instance, outputs a close future which can be used to determine when the session has been terminated. This allows in-flight requests to finish.

Parameters:

session – [in]

Returns:

A future that must be freed.

CassFuture *cass_session_prepare(CassSession *session, const char *query)¶

Create a prepared statement.

See also

cass_future_get_prepared()

Parameters:

• session – [in]

• query – [in] The query is copied into the statement object; the memory pointed to by this parameter can be freed after this call.

Returns:

A future that must be freed.

CassFuture *cass_session_prepare_n(CassSession *session, const char *query, size_t query_length)¶

Same as cass_session_prepare(), but with lengths for string parameters.

See also

cass_session_prepare()

Parameters:

• session – [in]

• query – [in]

• query_length – [in]

Returns:

same as cass_session_prepare()

CassFuture *cass_session_prepare_from_existing(CassSession *session, CassStatement *statement)¶

Create a prepared statement from an existing statement.

Note: Bound statements will inherit the keyspace, consistency, serial consistency, request timeout and retry policy of the existing statement.

See also

cass_future_get_prepared()

Parameters:

• session – [in]

• statement – [in]

Returns:

A future that must be freed.

CassFuture *cass_session_execute(CassSession *session, const CassStatement *statement)¶

Execute a query or bound statement.

See also

cass_future_get_result()

Parameters:

• session – [in]

• statement – [in]

Returns:

A future that must be freed.

CassFuture *cass_session_execute_batch(CassSession *session, const CassBatch *batch)¶

Execute a batch statement.

Requires Apache Cassandra: 2.0+

See also

cass_future_get_result()

Parameters:

• session – [in]

• batch – [in]

Returns:

A future that must be freed.

const CassSchemaMeta *cass_session_get_schema_meta(const CassSession *session)¶

Gets a snapshot of this session’s schema metadata. The returned snapshot of the schema metadata is not updated. This function must be called again to retrieve any schema changes since the previous call.

See also

cass_schema_meta_free()

Parameters:

session – [in]

Returns:

A schema instance that must be freed.

void cass_session_get_metrics(const CassSession *session, CassMetrics *output)¶

Gets a copy of this session’s performance/diagnostic metrics.

Parameters:

• session – [in]

• output – [out]

void cass_session_get_speculative_execution_metrics(const CassSession *session, CassSpeculativeExecutionMetrics *output)¶

Gets a copy of this session’s speculative execution metrics.

Parameters:

• session – [in]

• output – [out]

CassUuid cass_session_get_client_id(CassSession *session)¶

Get the client id.

Parameters:

session – [in]

Returns:

Client id.