CassExecProfile¶

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.

Public Functions

CassExecProfile *cass_execution_profile_new()¶

Creates a new execution profile.

See also

cass_execution_profile_free()

Returns:

Returns a execution profile that must be freed.

void cass_execution_profile_free(CassExecProfile *profile)¶

Frees a execution profile instance.

Parameters:

profile – [in]

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)

See also

cass_statement_set_request_timeout()

Parameters:

• profile – [in]

• timeout_ms – [in] Request timeout in milliseconds. Use 0 for no timeout or CASS_UINT64_MAX to disable.

Returns:

CASS_OK if successful, otherwise an error occurred.

CassError cass_execution_profile_set_consistency(CassExecProfile *profile, CassConsistency consistency)¶

Sets the consistency level.

Default: Disabled (uses the default consistency)

See also

cass_statement_set_consistency()

Parameters:

• profile – [in]

• consistency – [in]

Returns:

CASS_OK if successful, otherwise an error occurred.

CassError cass_execution_profile_set_serial_consistency(CassExecProfile *profile, CassConsistency serial_consistency)¶

Sets the serial consistency level.

Default: Disabled (uses the default serial consistency)

See also

cass_statement_set_serial_consistency()

Parameters:

• profile – [in]

• serial_consistency – [in]

Returns:

CASS_OK if successful, otherwise an error occurred.

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.

See also

cass_cluster_set_load_balance_round_robin()

Parameters:

profile – [in]

Returns:

CASS_OK if successful, otherwise an error occurred.

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.

See also

cass_cluster_set_load_balance_dc_aware()

Parameters:

• profile – [in]

• local_dc – [in] The primary data center to try first

• used_hosts_per_remote_dc – [in] The number of hosts used in each remote DC if no hosts are available in the local dc (deprecated)

• allow_remote_dcs_for_local_cl – [in] 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:

CASS_OK if successful, otherwise an error occurred.

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 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.

See also

cass_execution_profile_set_load_balance_dc_aware()

See also

cass_cluster_set_load_balance_dc_aware_n()

Parameters:

• profile – [in]

• local_dc – [in]

• local_dc_length – [in]

• used_hosts_per_remote_dc – [in] (deprecated)

• allow_remote_dcs_for_local_cl – [in] (deprecated)

Returns:

same as cass_execution_profile_set_load_balance_dc_aware()

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.

See also

cass_cluster_set_token_aware_routing()

Parameters:

• profile – [in]

• enabled – [in]

Returns:

CASS_OK if successful, otherwise an error occurred.

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

See also

cass_cluster_set_token_aware_routing_shuffle_replicas()

Parameters:

• profile – [in]

• enabled – [in]

Returns:

CASS_OK if successful, otherwise an error occurred.

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.

See also

cass_cluster_set_latency_aware_routing()

Parameters:

• profile – [in]

• enabled – [in]

Returns:

CASS_OK if successful, otherwise an error occurred.

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

See also

cass_cluster_set_latency_aware_routing_settings()

Parameters:

• profile – [in]

• exclusion_threshold – [in] Controls how much worse the latency must be compared to the average latency of the best performing node before it penalized.

• scale_ms – [in] 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.

• retry_period_ms – [in] 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).

• update_rate_ms – [in] The rate at which the best average latency is recomputed.

• min_measured – [in] The minimum number of measurements per-host required to be considered by the policy.

Returns:

CASS_OK if successful, otherwise an error occurred.

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.

See also

cass_cluster_set_whitelist_filtering()

Parameters:

• profile – [in]

• hosts – [in] 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:

CASS_OK if successful, otherwise an error occurred.

CassError cass_execution_profile_set_whitelist_filtering_n(CassExecProfile *profile, const char *hosts, size_t hosts_length)¶

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

See also

cass_execution_profile_set_whitelist_filtering()

See also

cass_cluster_set_whitelist_filtering()

Parameters:

• profile – [in]

• hosts – [in]

• hosts_length – [in]

Returns:

same as cass_execution_profile_set_whitelist_filtering()

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.

See also

cass_cluster_set_blacklist_filtering()

Parameters:

• profile – [in]

• hosts – [in] 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:

CASS_OK if successful, otherwise an error occurred.

CassError cass_execution_profile_set_blacklist_filtering_n(CassExecProfile *profile, const char *hosts, size_t hosts_length)¶

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

See also

cass_execution_profile_set_blacklist_filtering()

See also

cass_cluster_set_blacklist_filtering()

Parameters:

• profile – [in]

• hosts – [in]

• hosts_length – [in]

Returns:

same as cass_execution_profile_set_blacklist_filtering_hosts()

CassError cass_execution_profile_set_whitelist_dc_filtering(CassExecProfile *profile, const char *dcs)¶

Same as cass_execution_profile_set_whitelist_filtering(), but whitelist all hosts of a dc.

Examples: “dc1”, “dc1,dc2”

See also

cass_cluster_set_whitelist_dc_filtering()

Parameters:

• profile – [in]

• dcs – [in] 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:

CASS_OK if successful, otherwise an error occurred.

CassError cass_execution_profile_set_whitelist_dc_filtering_n(CassExecProfile *profile, const char *dcs, size_t dcs_length)¶

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

See also

cass_execution_profile_set_whitelist_dc_filtering()

See also

cass_cluster_set_whitelist_dc_filtering()

Parameters:

• profile – [in]

• dcs – [in]

• dcs_length – [in]

Returns:

same as cass_execution_profile_set_whitelist_dc_filtering()

CassError cass_execution_profile_set_blacklist_dc_filtering(CassExecProfile *profile, const char *dcs)¶

Same as cass_execution_profile_set_blacklist_filtering(), but blacklist all hosts of a dc.

Examples: “dc1”, “dc1,dc2”

See also

cass_execution_profile_set_blacklist_filtering()

See also

cass_cluster_set_blacklist_dc_filtering()

Parameters:

• profile – [in]

• dcs – [in] 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:

CASS_OK if successful, otherwise an error occurred.

CassError cass_execution_profile_set_blacklist_dc_filtering_n(CassExecProfile *profile, const char *dcs, size_t dcs_length)¶

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

See also

cass_execution_profile_set_blacklist_dc_filtering()

See also

cass_cluster_set_blacklist_dc_filtering()

Parameters:

• profile – [in]

• dcs – [in]

• dcs_length – [in]

Returns:

same as cass_execution_profile_set_blacklist_dc_filtering()

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.

See also

cass_cluster_set_retry_policy()

Parameters:

• profile – [in]

• retry_policy – [in] NULL will clear retry policy from execution profile

Returns:

CASS_OK if successful, otherwise an error occurred.

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.

See also

cass_cluster_set_constant_speculative_execution_policy()

Parameters:

• profile – [in]

• constant_delay_ms – [in]

• max_speculative_executions – [in]

Returns:

CASS_OK if successful, otherwise an error occurred

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.

See also

cass_cluster_set_no_speculative_execution_policy()

Parameters:

profile – [in]

Returns:

CASS_OK if successful, otherwise an error occurred