Unimplemented functions in `cassandra.h` - what we do about them

[wprzytula]

Current situation

There are quite a number of functions declared in cassandra.h which we don't implement in the wrapper. Currently, calling them in the user code will result in linker errors (unresolved symbols).

Problem

Linker errors because of unimplemented functions may be confusing. Also, they give no insight to the user whether the function is not implemented yet or it's not even planned to be ever implemented.

Suggested solution

Divide the unimplemented functions into two categories:

1. TODO.
2. Will never be implemented.

Functions that are TODO shall have it clearly stated in the docstring, so that their unimplementedness is visible to the user, along with the intention to eventually have it implemented.

Functions that we don't plan to ever implement shall be deleted from cassandra.h, not to confuse users. This makes users experience compiler errors instead of linker errors, which is normally less unexpected.

[wprzytula]

Suggested division of functions + rationale for never implementing each:

Never to be implemented functions

Custom types

• cass_collection_append_custom
• cass_collection_append_custom_n
• cass_statement_bind_custom
• cass_statement_bind_custom_by_name
• cass_statement_bind_custom_by_name_n
• cass_statement_bind_custom_n
• cass_tuple_set_custom
• cass_tuple_set_custom_n
• cass_value_get_custom

DataStax-specific features

• cass_cluster_set_cloud_secure_connection_bundle
• cass_cluster_set_cloud_secure_connection_bundle_n
• cass_cluster_set_cloud_secure_connection_bundle_no_ssl_lib_init
• cass_cluster_set_cloud_secure_connection_bundle_no_ssl_lib_init_n
• cass_cluster_set_monitor_reporting_interval

Deprecated in CPP Driver

• cass_cluster_set_queue_size_event
• cass_cluster_set_max_connections_per_host
• cass_cluster_set_reconnect_wait_time
• cass_cluster_set_max_concurrent_creation
• cass_cluster_set_max_concurrent_requests_threshold
• cass_cluster_set_max_requests_per_flush
• cass_cluster_set_write_bytes_high_water_mark
• cass_cluster_set_write_bytes_low_water_mark
• cass_cluster_set_pending_requests_high_water_mark
• cass_cluster_set_pending_requests_low_water_mark
• cass_log_cleanup
• cass_log_set_queue_size

Ancient features

• cass_cluster_set_no_compact
• cass_cluster_set_use_hostname_resolution - I see no point in disabling hostname resolution.

Incompatible with the Rust Driver's architecture

• cass_cluster_set_new_request_ratio
• cass_cluster_set_max_reusable_write_objects
• cass_cluster_set_queue_size_io

Metadata raw string accessors

Semantics of these require internal storage of metadata in a raw string form, which is not true in Rust Driver.

• cass_aggregate_meta_field_by_name
• cass_aggregate_meta_field_by_name_n
• cass_function_meta_field_by_name
• cass_function_meta_field_by_name_n
• cass_index_meta_field_by_name
• cass_index_meta_field_by_name_n
• cass_keyspace_meta_field_by_name
• cass_keyspace_meta_field_by_name_n
• cass_table_meta_field_by_name
• cass_table_meta_field_by_name_n
• cass_materialized_view_meta_field_by_name
• cass_materialized_view_meta_field_by_name_n
• cass_column_meta_field_by_name
• cass_column_meta_field_by_name_n
• cass_iterator_fields_from_aggregate_meta
• cass_iterator_fields_from_column_meta
• cass_iterator_fields_from_function_meta
• cass_iterator_fields_from_index_meta
• cass_iterator_fields_from_keyspace_meta
• cass_iterator_fields_from_materialized_view_meta
• cass_iterator_fields_from_table_meta
• cass_iterator_get_meta_field_name
• cass_iterator_get_meta_field_value

Purposely unimplemented

• cass_statement_add_key_index - binding values to unprepared statements is risky and unsupported.
• cass_cluster_set_prepare_on_up_or_add_host - cluster events are unreliable and this optimisation is unlikely to work well.

Request tracing

Explanation: the semantics is weird. CPP Driver waits for tracing info to become available by performing queries to tracing tables with the parameters specified by the following functions. The problem is, it does not expose the results of the query; it's the user's responsibility to fetch them themselves again. This is inefficient and real pain. Therefore, we prefer the driver to provide no functionalities regarding server-side tracing, so the user must query tracing tables themselves, than to provide such a weird and incomplete semantics.

• cass_cluster_set_tracing_consistency
• cass_cluster_set_tracing_max_wait_time
• cass_cluster_set_tracing_retry_wait_time

Planned functions

Custom allocator

• cass_alloc_set_functions - requires investigation if it's feasible.

Host event listener

• cass_cluster_set_host_listener_callback - only if and once we introduce such API in the Rust Driver.

Custom payload

• cass_custom_payload_free
• cass_custom_payload_new
• cass_custom_payload_remove
• cass_custom_payload_remove_n
• cass_custom_payload_set
• cass_custom_payload_set_n
• cass_future_custom_payload_item
• cass_future_custom_payload_item_count
• cass_statement_set_custom_payload
• cass_batch_set_custom_payload

Speculative execution metrics

• cass_session_get_speculative_execution_metrics

Reconnect policy

• cass_cluster_set_constant_reconnect
• cass_cluster_set_exponential_reconnect

DNS resolution timeout

• cass_cluster_set_resolve_timeout

Randomized contact points

• cass_cluster_set_use_randomized_contact_points

Getting cluster/node DB version

• cass_schema_meta_version

Setting keyspace on statements (only if and once native protocol v5 is supported by ScyllaDB)

• cass_batch_set_keyspace
• cass_batch_set_keyspace_n
• cass_statement_set_keyspace
• cass_statement_set_keyspace_n

Allowing prepare on a single host

• cass_cluster_set_prepare_on_all_hosts

Metadata

Metadata snapshot versioning

• cass_schema_meta_snapshot_version

Aggregates

• cass_aggregate_meta_argument_count
• cass_aggregate_meta_argument_type
• cass_aggregate_meta_final_func
• cass_aggregate_meta_full_name
• cass_aggregate_meta_init_cond
• cass_aggregate_meta_name
• cass_aggregate_meta_return_type
• cass_aggregate_meta_state_func
• cass_aggregate_meta_state_type
• cass_iterator_aggregates_from_keyspace_meta
• cass_iterator_get_aggregate_meta

Functions

• cass_function_meta_argument
• cass_function_meta_argument_count
• cass_function_meta_argument_type_by_name
• cass_function_meta_argument_type_by_name_n
• cass_function_meta_body
• cass_function_meta_called_on_null_input
• cass_function_meta_full_name
• cass_function_meta_language
• cass_function_meta_name
• cass_function_meta_return_type
• cass_iterator_functions_from_keyspace_meta
• cass_iterator_get_function_meta

Indexes

• cass_index_meta_name
• cass_index_meta_options
• cass_index_meta_target
• cass_index_meta_type
• cass_iterator_get_index_meta
• cass_iterator_indexes_from_table_meta

Keyspaces

• cass_keyspace_meta_aggregate_by_name
• cass_keyspace_meta_aggregate_by_name_n
• cass_keyspace_meta_function_by_name
• cass_keyspace_meta_function_by_name_n
• cass_keyspace_meta_is_virtual

Materialized Views

• cass_materialized_view_meta_clustering_key_order

Tables:

• cass_table_meta_clustering_key_order
• cass_table_meta_index
• cass_table_meta_index_by_name
• cass_table_meta_index_by_name_n
• cass_table_meta_index_count
• cass_table_meta_is_virtual

Authentication API

• cass_cluster_set_authenticator_callbacks
• cass_authenticator_address
• cass_authenticator_class_name
• cass_authenticator_exchange_data
• cass_authenticator_hostname
• cass_authenticator_response
• cass_authenticator_set_error
• cass_authenticator_set_error_n
• cass_authenticator_set_exchange_data
• cass_authenticator_set_response

[wprzytula]

@dkropachev @Lorak-mmk please review the above list. Let's discuss any controversial choices.

Then, once we reach the consensus, I'll:

1. Delete the never-to-be-implemented functions from cassandra.h.
2. Put the list of these functions along with explanation why it was removed in some new file, say DELETED_API.md.
3. Mark the unimplemented-yet-planned functions in cassandra.h with some text, say:

WARNING: This function is not yet implemented in the CPP RS Driver.

4. Update the README.md Limitations section by deleting never-to-be-implemented functions. Also, I think I'll add a per-feature list of missing functions (which is written in this issue above), along with the per-class list which is already present there.

[wprzytula]

v1.1:

• moved cass_alloc_set_functions and cass_cluster_set_host_listener_callback to the planned section.

[wprzytula]

@dkropachev Together with Karol we agree to have another package with stubs of unimplemented functions, as long as the default build workflow and the default package do not contain those stubs.

[wprzytula]

v1.2:

• added cass_log_cleanup and cass_log_queue_size to the deprecated functions section.