struct CassExecProfile

An execution profile object provides a mechanism to group together a set of configuration options and reuse them across different statement executions. This feature is useful when dealing with different query workloads.

Functions

CassExecProfile *

cass_execution_profile_new

( )

Creates a new execution profile.

Returns:
Type Details
CassExecProfile *

Returns a execution profile that must be freed.
See Also:
void

cass_execution_profile_free

( CassExecProfile * profile )

Frees a execution profile instance.

Parameters:
Name Type Details
in profile CassExecProfile *
CassError

cass_execution_profile_set_request_timeout

( CassExecProfile * profile, cass_uint64_t timeout_ms )

Sets the timeout waiting for a response from a node.

Default: Disabled (uses the cluster request timeout)

Parameters:
Name Type Details
in profile CassExecProfile *
in timeout_ms cass_uint64_t

Request timeout in milliseconds. Use 0 for no timeout or CASS_UINT64_MAX to disable.
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_consistency

( CassExecProfile * profile, CassConsistency consistency )

Sets the consistency level.

Default: Disabled (uses the default consistency)

Parameters:
Name Type Details
in profile CassExecProfile *
in consistency CassConsistency
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_serial_consistency

( CassExecProfile * profile, CassConsistency serial_consistency )

Sets the serial consistency level.

Default: Disabled (uses the default serial consistency)

Parameters:
Name Type Details
in profile CassExecProfile *
in serial_consistency CassConsistency
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_load_balance_round_robin

( CassExecProfile * profile )

Configures the execution profile to use round-robin load balancing.

The driver discovers all nodes in a cluster and cycles through them per request. All are considered ‘local’.

Note: Profile-based load balancing policy is disabled by default; cluster load balancing policy is used when profile does not contain a policy.

Parameters:
Name Type Details
in profile CassExecProfile *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_load_balance_dc_aware

( CassExecProfile * profile, const char * local_dc, unsigned used_hosts_per_remote_dc, cass_bool_t allow_remote_dcs_for_local_cl )

Configures the execution profile to use DC-aware load balancing. For each query, all live nodes in a primary ‘local’ DC are tried first, followed by any node from other DCs.

Note: Profile-based load balancing policy is disabled by default; cluster load balancing policy is used when profile does not contain a policy.

Deprecated:

The remote DC settings for DC-aware are not suitable for most scenarios that require DC failover. There is also unhandled gap between replication factor number of nodes failing and the full cluster failing. Only the remote DC settings are being deprecated.

Parameters:
Name Type Details
in profile CassExecProfile *
in local_dc const char *

The primary data center to try first
in used_hosts_per_remote_dc unsigned

The number of hosts used in each remote DC if no hosts are available in the local dc (deprecated)
in allow_remote_dcs_for_local_cl cass_bool_t

Allows remote hosts to be used if no local dc hosts are available and the consistency level is LOCAL_ONE or LOCAL_QUORUM (deprecated)
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_load_balance_dc_aware_n

( CassExecProfile * profile, const char * local_dc, size_t local_dc_length, unsigned used_hosts_per_remote_dc, cass_bool_t allow_remote_dcs_for_local_cl )

Same as CassExecProfile::cass_execution_profile_set_load_balance_dc_aware, but with lengths for string parameters.

Deprecated:

The remote DC settings for DC-aware are not suitable for most scenarios that require DC failover. There is also unhandled gap between replication factor number of nodes failing and the full cluster failing. Only the remote DC settings are being deprecated.

Parameters:
Name Type Details
in profile CassExecProfile *
in local_dc const char *
in local_dc_length size_t
in used_hosts_per_remote_dc unsigned

(deprecated)
in allow_remote_dcs_for_local_cl cass_bool_t

(deprecated)
Returns:
Type Details
CassError

same as CassExecProfile::cass_execution_profile_set_load_balance_dc_aware
See Also:
CassError

cass_execution_profile_set_token_aware_routing

( CassExecProfile * profile, cass_bool_t enabled )

Configures the execution profile to use token-aware request routing or not.

Important: Token-aware routing depends on keyspace metadata. For this reason enabling token-aware routing will also enable retrieving and updating keyspace schema metadata.

Default: cass_true (enabled).

This routing policy composes the base routing policy, routing requests first to replicas on nodes considered ‘local’ by the base load balancing policy.

Note: Execution profiles use the cluster-level load balancing policy unless enabled. This setting is not applicable unless a load balancing policy is enabled on the execution profile.

Parameters:
Name Type Details
in profile CassExecProfile *
in enabled cass_bool_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_token_aware_routing_shuffle_replicas

( CassExecProfile * profile, cass_bool_t enabled )

Configures the execution profile’s token-aware routing to randomly shuffle replicas. This can reduce the effectiveness of server-side caching, but it can better distribute load over replicas for a given partition key.

Note: Token-aware routing must be enabled and a load balancing policy must be enabled on the execution profile for the setting to be applicable.

Default: cass_true (enabled).

Parameters:
Name Type Details
in profile CassExecProfile *
in enabled cass_bool_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_latency_aware_routing

( CassExecProfile * profile, cass_bool_t enabled )

Configures the execution profile to use latency-aware request routing or not.

Note: Execution profiles use the cluster-level load balancing policy unless enabled. This setting is not applicable unless a load balancing policy is enabled on the execution profile.

Default: cass_false (disabled).

This routing policy is a top-level routing policy. It uses the base routing policy to determine locality (dc-aware) and/or placement (token-aware) before considering the latency.

Parameters:
Name Type Details
in profile CassExecProfile *
in enabled cass_bool_t
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_latency_aware_routing_settings

( CassExecProfile * profile, cass_double_t exclusion_threshold, cass_uint64_t scale_ms, cass_uint64_t retry_period_ms, cass_uint64_t update_rate_ms, cass_uint64_t min_measured )

Configures the execution profile’s settings for latency-aware request routing.

Note: Execution profiles use the cluster-level load balancing policy unless enabled. This setting is not applicable unless a load balancing policy is enabled on the execution profile.

Defaults:

  • exclusion_threshold: 2.0
  • scale_ms: 100 milliseconds
  • retry_period_ms: 10,000 milliseconds (10 seconds)
  • update_rate_ms: 100 milliseconds
  • min_measured: 50
Parameters:
Name Type Details
in profile CassExecProfile *
in exclusion_threshold cass_double_t

Controls how much worse the latency must be compared to the average latency of the best performing node before it penalized.
in scale_ms cass_uint64_t

Controls the weight given to older latencies when calculating the average latency of a node. A bigger scale will give more weight to older latency measurements.
in retry_period_ms cass_uint64_t

The amount of time a node is penalized by the policy before being given a second chance when the current average latency exceeds the calculated threshold (exclusion_threshold * best_average_latency).
in update_rate_ms cass_uint64_t

The rate at which the best average latency is recomputed.
in min_measured cass_uint64_t

The minimum number of measurements per-host required to be considered by the policy.
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_whitelist_filtering

( CassExecProfile * profile, const char * hosts )

Sets/Appends whitelist hosts for the execution profile. The first call sets the whitelist hosts and any subsequent calls appends additional hosts. Passing an empty string will clear and disable the whitelist. White space is striped from the hosts.

This policy filters requests to all other policies, only allowing requests to the hosts contained in the whitelist. Any host not in the whitelist will be ignored and a connection will not be established. This policy is useful for ensuring that the driver will only connect to a predefined set of hosts.

Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”

Note: Execution profiles use the cluster-level load balancing policy unless enabled. This setting is not applicable unless a load balancing policy is enabled on the execution profile.

Parameters:
Name Type Details
in profile CassExecProfile *
in hosts const char *

A comma delimited list of addresses. An empty string will clear the whitelist hosts. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_whitelist_filtering_n

( CassExecProfile * profile, const char * hosts, size_t hosts_length )

Same as CassExecProfile::cass_execution_profile_set_whitelist_filtering, but with lengths for string parameters.

Parameters:
Name Type Details
in profile CassExecProfile *
in hosts const char *
in hosts_length size_t
Returns:
Type Details
CassError

same as CassExecProfile::cass_execution_profile_set_whitelist_filtering
See Also:
CassError

cass_execution_profile_set_blacklist_filtering

( CassExecProfile * profile, const char * hosts )

Sets/Appends blacklist hosts for the execution profile. The first call sets the blacklist hosts and any subsequent calls appends additional hosts. Passing an empty string will clear and disable the blacklist. White space is striped from the hosts.

This policy filters requests to all other policies, only allowing requests to the hosts not contained in the blacklist. Any host in the blacklist will be ignored and a connection will not be established. This policy is useful for ensuring that the driver will not connect to a predefined set of hosts.

Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”

Note: Execution profiles use the cluster-level load balancing policy unless enabled. This setting is not applicable unless a load balancing policy is enabled on the execution profile.

Parameters:
Name Type Details
in profile CassExecProfile *
in hosts const char *

A comma delimited list of addresses. An empty string will clear the blacklist hosts. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_blacklist_filtering_n

( CassExecProfile * profile, const char * hosts, size_t hosts_length )

Same as CassExecProfile::cass_execution_profile_set_blacklist_filtering, but with lengths for string parameters.

Parameters:
Name Type Details
in profile CassExecProfile *
in hosts const char *
in hosts_length size_t
Returns:
Type Details
CassError

same as cass_execution_profile_set_blacklist_filtering_hosts()
See Also:
CassError

cass_execution_profile_set_whitelist_dc_filtering

( CassExecProfile * profile, const char * dcs )

Same as CassExecProfile::cass_execution_profile_set_whitelist_filtering, but whitelist all hosts of a dc.

Examples: “dc1”, “dc1,dc2”

Parameters:
Name Type Details
in profile CassExecProfile *
in dcs const char *

A comma delimited list of dcs. An empty string will clear the whitelist dcs. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_whitelist_dc_filtering_n

( CassExecProfile * profile, const char * dcs, size_t dcs_length )

Same as CassExecProfile::cass_execution_profile_set_whitelist_dc_filtering, but with lengths for string parameters.

Parameters:
Name Type Details
in profile CassExecProfile *
in dcs const char *
in dcs_length size_t
Returns:
Type Details
CassError

same as CassExecProfile::cass_execution_profile_set_whitelist_dc_filtering
See Also:
CassError

cass_execution_profile_set_blacklist_dc_filtering

( CassExecProfile * profile, const char * dcs )

Same as CassExecProfile::cass_execution_profile_set_blacklist_filtering, but blacklist all hosts of a dc.

Examples: “dc1”, “dc1,dc2”

Parameters:
Name Type Details
in profile CassExecProfile *
in dcs const char *

A comma delimited list of dcs. An empty string will clear the blacklist dcs. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_blacklist_dc_filtering_n

( CassExecProfile * profile, const char * dcs, size_t dcs_length )

Same as CassExecProfile::cass_execution_profile_set_blacklist_dc_filtering, but with lengths for string parameters.

Parameters:
Name Type Details
in profile CassExecProfile *
in dcs const char *
in dcs_length size_t
Returns:
Type Details
CassError

same as CassExecProfile::cass_execution_profile_set_blacklist_dc_filtering
See Also:
CassError

cass_execution_profile_set_retry_policy

( CassExecProfile * profile, CassRetryPolicy * retry_policy )

Sets the execution profile’s retry policy.

Note: Profile-based retry policy is disabled by default; cluster retry policy is used when profile does not contain a policy unless the retry policy was explicitly set on the batch/statement request.

Parameters:
Name Type Details
in profile CassExecProfile *
in retry_policy CassRetryPolicy *

NULL will clear retry policy from execution profile
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.
See Also:
CassError

cass_execution_profile_set_constant_speculative_execution_policy

( CassExecProfile * profile, cass_int64_t constant_delay_ms, int max_speculative_executions )

Enable constant speculative executions with the supplied settings for the execution profile.

Note: Profile-based speculative execution policy is disabled by default; cluster speculative execution policy is used when profile does not contain a policy.

Parameters:
Name Type Details
in profile CassExecProfile *
in constant_delay_ms cass_int64_t
in max_speculative_executions int
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred
See Also:
CassError

cass_execution_profile_set_no_speculative_execution_policy

( CassExecProfile * profile )

Disable speculative executions for the execution profile.

Note: Profile-based speculative execution policy is disabled by default; cluster speculative execution policy is used when profile does not contain a policy.

Parameters:
Name Type Details
in profile CassExecProfile *
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred
See Also: