ilios 1.0.6 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae1db76d702cb217eb8145f498dd86044183e441cbd896ac6acfd0d118823d13
-  data.tar.gz: 5e5e141d2578bdfd5c2b39b8b7e5b72e5a65de824a4e5868c3388e3308973d8c
+  metadata.gz: 35886070e9a98cd40ab1628296e5f2a1cf50fcd5f8429ade4d79eeb0a363cf29
+  data.tar.gz: e6b9d75e242db36c5fc96774fbf2dd31a135b3702ccaedc57e3efb07cd1fa22b
 SHA512:
-  metadata.gz: 2c78135d42da8f1c532c80531d0a493fed7f4bcf96ddf2d8aabdafac649740cb819a6f038640031993fe33fdc82c245e9725868f71149751aaaadf9ca3710d0b
-  data.tar.gz: 26771b46cf175596fdd14a19873783c151f3a1b02798ca43fa39b7828b8519a3316bbcafbc93a291d9c44cadb95d562c1e7fc6d30b19e48e2efb28592c72c674
+  metadata.gz: 2219b69eef45cc7977f79354bf4e03fc8e7583f59ed91dc4290653a0e1a0ea669d9b5dd1225b8cb043203824d3c6d4bf5294baee658e3f07d8ac04be87422c3c
+  data.tar.gz: 7e7919c71dd7d876f84331ad33f2b66a9c0831bd5b342eaf766a6e6794e018183b1ba48e798eebb1305480031464c426c11ee79ec490d2d5fec56d826239cf14

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## 1.1.0
+
+- Support Cassandra collection types (`list`, `set` and `map`, including nested collections). `list` maps to `Array`, `set` to `Set`, `map` to `Hash` (#28)
+- Accept `Symbol` values for `text`/`ascii`/`varchar` columns and collection elements (#28)
+- Require Ruby 3.4 or later (#28)
+- Fix `Ilios::Cassandra::Future#await` returning before the registered callback ran (PR #29)
+
 ## 1.0.6
 
 - Fix uninitialized memory being returned for an undecodable column value (#27)

data/Gemfile

@@ -15,4 +15,4 @@ gem 'rubocop-minitest', '~> 0.33'
 gem 'rubocop-performance', '~> 1.19'
 gem 'rubocop-rake', '~> 0.6'
 
-gem 'rubocop-on-rbs', '~> 1.5' if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.2')
+gem 'rubocop-on-rbs', '~> 1.5'

data/README.md

@@ -2,6 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/ilios.svg)](https://badge.fury.io/rb/ilios)
 [![CI](https://github.com/Watson1978/ilios/actions/workflows/CI.yml/badge.svg)](https://github.com/Watson1978/ilios/actions/workflows/CI.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Watson1978/ilios)
 
 Ilios that Cassandra driver written by C language for Ruby using [DataStax C/C++ Driver](https://github.com/datastax/cpp-driver).
 
@@ -42,7 +43,7 @@ $ gem install ilios -- --with-libuv-dir=/path/to/libuv-installed-dir --with-cass
 
 ## Supported
 
-- Ruby 3.1 or later
+- Ruby 3.4 or later
 - Cassandra 3.0 or later
 - Linux and macOS platform
 
@@ -117,6 +118,59 @@ while(result.next_page)
 end
 ```
 
+### Collection types
+
+`list`, `set` and `map` columns (including nested collections such as
+`list<frozen<list<int>>>`) are supported.
+
+```ruby
+statement = session.prepare(<<~CQL)
+  CREATE TABLE IF NOT EXISTS ilios.collection_example (
+    id bigint,
+    tags set<text>,
+    scores list<int>,
+    attributes map<text, bigint>,
+    PRIMARY KEY (id)
+  );
+CQL
+session.execute(statement)
+
+statement = session.prepare(<<~CQL)
+  INSERT INTO ilios.collection_example (
+    id,
+    tags,
+    scores,
+    attributes
+  ) VALUES (?, ?, ?, ?)
+CQL
+statement.bind({
+  id: 1,
+  tags: Set['ruby', 'cassandra'],  # or an Array
+  scores: [85, 92],
+  attributes: { 'height' => 180 },
+})
+session.execute(statement)
+
+statement = session.prepare(<<~CQL)
+  SELECT * FROM ilios.collection_example
+CQL
+session.execute(statement).each do |row|
+  row['tags']       # => Set["cassandra", "ruby"]
+  row['scores']     # => [85, 92]
+  row['attributes'] # => {"height" => 180}
+end
+```
+
+Notes:
+
+- A `set` column accepts both `Set` and `Array` on bind, and is always returned as a `Set`.
+- A `list` column also accepts both `Array` and `Set` on bind, but is always returned as an `Array`. Binding a `Set` to a `list` column keeps the order `Set#to_a` returns.
+- Cassandra stores an empty non-frozen collection as `null`, so inserting `[]`, `Set.new` or `{}` returns `nil` on select. This is Cassandra's data model, not an Ilios limitation.
+- `nil` is not allowed as a collection element (Cassandra collections cannot contain `null`).
+- `Symbol` is accepted for `text` (as well as `ascii` and `varchar`) columns and collection elements, and is stored (and returned) as a `String`.
+- Because a `Symbol` map key is stored as its `String` equivalent, binding a map that contains both (for example `{ k1: 1, 'k1' => 2 }`) ends up as a single key on the server; the entry bound last wins.
+- Binding a `String` containing a NUL character (`\0`) to a `text` (or `ascii` / `varchar`) column raises `ArgumentError` (known limitation).
+
 ### Synchronous API
 `Ilios::Cassandra::Session#prepare` and `Ilios::Cassandra::Session#execute` are provided as synchronous API.
 

data/ext/ilios/future.c

@@ -213,6 +213,7 @@ VALUE future_create(CassFuture *future, VALUE session, VALUE statement, future_k
     uv_sem_init(&cassandra_future->sem, 0);
     cassandra_future->already_waited = false;
     cassandra_future->yielded = false;
+    cassandra_future->queued = false;
 
     return cassandra_future_obj;
 }
@@ -232,7 +233,11 @@ static VALUE future_on_success_synchronize(VALUE future)
     RB_OBJ_WRITE(future, &cassandra_future->on_success_block, rb_block_proc());
 
     if (cass_future_ready(cassandra_future->future)) {
-        uv_sem_post(&cassandra_future->sem);
+        // The pool thread posts the semaphore itself once it has yielded;
+        // posting here too would let #await return before that happens.
+        if (!cassandra_future->queued) {
+            uv_sem_post(&cassandra_future->sem);
+        }
         if (!cassandra_future->yielded &&
             cass_future_error_code(cassandra_future->future) == CASS_OK) {
             cassandra_future->yielded = true;
@@ -242,6 +247,7 @@ static VALUE future_on_success_synchronize(VALUE future)
     }
 
     if (wakeup_thread) {
+        cassandra_future->queued = true;
         future_queue_push(future_thread_pool_get(cassandra_future), future);
     }
 
@@ -289,7 +295,9 @@ static VALUE future_on_failure_synchronize(VALUE future)
     RB_OBJ_WRITE(future, &cassandra_future->on_failure_block, rb_block_proc());
 
     if (cass_future_ready(cassandra_future->future)) {
-        uv_sem_post(&cassandra_future->sem);
+        if (!cassandra_future->queued) {
+            uv_sem_post(&cassandra_future->sem);
+        }
         if (!cassandra_future->yielded &&
             cass_future_error_code(cassandra_future->future) != CASS_OK) {
             cassandra_future->yielded = true;
@@ -299,6 +307,7 @@ static VALUE future_on_failure_synchronize(VALUE future)
     }
 
     if (wakeup_thread) {
+        cassandra_future->queued = true;
         future_queue_push(future_thread_pool_get(cassandra_future), future);
     }
 

data/ext/ilios/ilios.c

@@ -12,8 +12,10 @@ VALUE eExecutionError;
 VALUE eStatementError;
 
 VALUE cSizedQueue;
+VALUE cSet;
 
 VALUE id_to_time;
+VALUE id_to_a;
 VALUE id_new;
 VALUE id_push;
 VALUE id_pop;
@@ -88,8 +90,12 @@ void Init_ilios(void)
     eStatementError = rb_define_class_under(mCassandra, "StatementError", rb_eStandardError);
 
     cSizedQueue = rb_const_get(rb_cThread, rb_intern("SizedQueue"));
+    rb_require("set");
+    cSet = rb_const_get(rb_cObject, rb_intern("Set"));
+    rb_gc_register_mark_object(cSet);
 
     id_to_time = rb_intern("to_time");
+    id_to_a = rb_intern("to_a");
     id_new = rb_intern("new");
     id_push = rb_intern("push");
     id_pop = rb_intern("pop");

data/ext/ilios/ilios.h

@@ -87,6 +87,8 @@ typedef struct
     uv_sem_t sem;
     bool already_waited;
     bool yielded;
+    // Handed to the thread pool, which posts the semaphore once it is done.
+    bool queued;
 } CassandraFuture;
 
 extern const rb_data_type_t cassandra_cluster_data_type;
@@ -107,8 +109,10 @@ extern VALUE eExecutionError;
 extern VALUE eStatementError;
 
 extern VALUE cSizedQueue;
+extern VALUE cSet;
 
 extern VALUE id_to_time;
+extern VALUE id_to_a;
 extern VALUE id_new;
 extern VALUE id_push;
 extern VALUE id_pop;

data/ext/ilios/result.c

@@ -87,6 +87,163 @@ static void result_check_value(CassError error_code, VALUE key)
     }
 }
 
+static VALUE result_convert_value(const CassValue *value, VALUE key);
+
+struct result_convert_collection_arg {
+    CassIterator *iterator;
+    CassValueType type;
+    VALUE key;
+};
+
+static VALUE result_convert_collection_body(VALUE a)
+{
+    struct result_convert_collection_arg *args = (struct result_convert_collection_arg *)a;
+
+    if (args->type == CASS_VALUE_TYPE_MAP) {
+        VALUE hash = rb_hash_new();
+
+        while (cass_iterator_next(args->iterator)) {
+            VALUE k = result_convert_value(cass_iterator_get_map_key(args->iterator), args->key);
+            VALUE v = result_convert_value(cass_iterator_get_map_value(args->iterator), args->key);
+            rb_hash_aset(hash, k, v);
+        }
+        return hash;
+    } else {
+        VALUE array = rb_ary_new();
+
+        while (cass_iterator_next(args->iterator)) {
+            rb_ary_push(array, result_convert_value(cass_iterator_get_value(args->iterator), args->key));
+        }
+        if (args->type == CASS_VALUE_TYPE_SET) {
+            return rb_funcall(cSet, id_new, 1, array);
+        }
+        return array;
+    }
+}
+
+static VALUE result_convert_collection_ensure(VALUE a)
+{
+    cass_iterator_free((CassIterator *)a);
+    return Qnil;
+}
+
+static VALUE result_convert_collection(const CassValue *value, CassValueType type, VALUE key)
+{
+    struct result_convert_collection_arg args;
+    CassIterator *iterator;
+
+    if (type == CASS_VALUE_TYPE_MAP) {
+        iterator = cass_iterator_from_map(value);
+    } else {
+        iterator = cass_iterator_from_collection(value);
+    }
+    if (iterator == NULL) {
+        // NULL collections are filtered out by cass_value_is_null in
+        // result_convert_value; this is a safety net.
+        return Qnil;
+    }
+
+    args.iterator = iterator;
+    args.type = type;
+    args.key = key;
+    return rb_ensure(result_convert_collection_body, (VALUE)&args, result_convert_collection_ensure, (VALUE)iterator);
+}
+
+static VALUE result_convert_value(const CassValue *value, VALUE key)
+{
+    const CassValueType type = cass_value_type(value);
+
+    if (cass_value_is_null(value)) {
+        return Qnil;
+    }
+
+    switch (type) {
+    case CASS_VALUE_TYPE_TINY_INT:
+        {
+            cass_int8_t output = 0;
+            result_check_value(cass_value_get_int8(value, &output), key);
+            return INT2NUM(output);
+        }
+
+    case CASS_VALUE_TYPE_SMALL_INT:
+        {
+            cass_int16_t output = 0;
+            result_check_value(cass_value_get_int16(value, &output), key);
+            return INT2NUM(output);
+        }
+
+    case CASS_VALUE_TYPE_INT:
+        {
+            cass_int32_t output = 0;
+            result_check_value(cass_value_get_int32(value, &output), key);
+            return INT2NUM(output);
+        }
+
+    case CASS_VALUE_TYPE_BIGINT:
+        {
+            cass_int64_t output = 0;
+            result_check_value(cass_value_get_int64(value, &output), key);
+            return LL2NUM(output);
+        }
+
+    case CASS_VALUE_TYPE_FLOAT:
+        {
+            cass_float_t output = 0;
+            result_check_value(cass_value_get_float(value, &output), key);
+            return DBL2NUM(output);
+        }
+
+    case CASS_VALUE_TYPE_DOUBLE:
+        {
+            cass_double_t output = 0;
+            result_check_value(cass_value_get_double(value, &output), key);
+            return DBL2NUM(output);
+        }
+
+    case CASS_VALUE_TYPE_BOOLEAN:
+        {
+            cass_bool_t output = cass_false;
+            result_check_value(cass_value_get_bool(value, &output), key);
+            return output == cass_true ? Qtrue : Qfalse;
+        }
+
+    case CASS_VALUE_TYPE_TEXT:
+    case CASS_VALUE_TYPE_ASCII:
+    case CASS_VALUE_TYPE_VARCHAR:
+        {
+            const char* s = NULL;
+            size_t s_length = 0;
+            result_check_value(cass_value_get_string(value, &s, &s_length), key);
+            return rb_str_new(s, s_length);
+        }
+
+    case CASS_VALUE_TYPE_TIMESTAMP:
+        {
+            cass_int64_t output = 0;
+            result_check_value(cass_value_get_int64(value, &output), key);
+            return rb_time_new(output / 1000, output % 1000 * 1000);
+        }
+
+    case CASS_VALUE_TYPE_UUID:
+        {
+            CassUuid output = { 0, 0 };
+            char uuid[40];
+            result_check_value(cass_value_get_uuid(value, &output), key);
+            cass_uuid_string(output, uuid);
+            return rb_str_new2(uuid);
+        }
+
+    case CASS_VALUE_TYPE_LIST:
+    case CASS_VALUE_TYPE_SET:
+    case CASS_VALUE_TYPE_MAP:
+        return result_convert_collection(value, type, key);
+
+    default:
+        rb_warn("Unsupported type: %d", type);
+        return sym_unsupported_column_type;
+    }
+}
+
 static VALUE result_convert_row(const CassResult *result, const CassRow *row, size_t column_count)
 {
     VALUE key;
@@ -96,106 +253,10 @@ static VALUE result_convert_row(const CassResult *result, const CassRow *row, si
 
     for (size_t i = 0; i < column_count; i++) {
         const CassValue *value = cass_row_get_column(row, i);
-        const CassValueType type = cass_value_type(value);
 
         cass_result_column_name(result, i, &name, &name_length);
         key = rb_enc_interned_str(name, name_length, rb_utf8_encoding());
-
-        if (cass_value_is_null(value)) {
-            rb_hash_aset(hash, key, Qnil);
-            continue;
-        }
-
-        switch (type) {
-        case CASS_VALUE_TYPE_TINY_INT:
-            {
-                cass_int8_t output = 0;
-                result_check_value(cass_value_get_int8(value, &output), key);
-                rb_hash_aset(hash, key, INT2NUM(output));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_SMALL_INT:
-            {
-                cass_int16_t output = 0;
-                result_check_value(cass_value_get_int16(value, &output), key);
-                rb_hash_aset(hash, key, INT2NUM(output));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_INT:
-            {
-                cass_int32_t output = 0;
-                result_check_value(cass_value_get_int32(value, &output), key);
-                rb_hash_aset(hash, key, INT2NUM(output));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_BIGINT:
-            {
-                cass_int64_t output = 0;
-                result_check_value(cass_value_get_int64(value, &output), key);
-                rb_hash_aset(hash, key, LL2NUM(output));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_FLOAT:
-            {
-                cass_float_t output = 0;
-                result_check_value(cass_value_get_float(value, &output), key);
-                rb_hash_aset(hash, key, DBL2NUM(output));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_DOUBLE:
-            {
-                cass_double_t output = 0;
-                result_check_value(cass_value_get_double(value, &output), key);
-                rb_hash_aset(hash, key, DBL2NUM(output));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_BOOLEAN:
-            {
-                cass_bool_t output = cass_false;
-                result_check_value(cass_value_get_bool(value, &output), key);
-                rb_hash_aset(hash, key, output == cass_true ? Qtrue : Qfalse);
-            }
-            break;
-
-        case CASS_VALUE_TYPE_TEXT:
-        case CASS_VALUE_TYPE_ASCII:
-        case CASS_VALUE_TYPE_VARCHAR:
-            {
-                const char* s = NULL;
-                size_t s_length = 0;
-                result_check_value(cass_value_get_string(value, &s, &s_length), key);
-                rb_hash_aset(hash, key, rb_str_new(s, s_length));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_TIMESTAMP:
-            {
-                cass_int64_t output = 0;
-                result_check_value(cass_value_get_int64(value, &output), key);
-                rb_hash_aset(hash, key, rb_time_new(output / 1000, output % 1000 * 1000));
-            }
-            break;
-
-        case CASS_VALUE_TYPE_UUID:
-            {
-                CassUuid output = { 0, 0 };
-                char uuid[40];
-                result_check_value(cass_value_get_uuid(value, &output), key);
-                cass_uuid_string(output, uuid);
-                rb_hash_aset(hash, key, rb_str_new2(uuid));
-            }
-            break;
-
-        default:
-            rb_warn("Unsupported type: %d", type);
-            rb_hash_aset(hash, key, sym_unsupported_column_type);
-        }
+        rb_hash_aset(hash, key, result_convert_value(value, key));
     }
 
     return hash;

data/ext/ilios/statement.c

@@ -24,6 +24,107 @@ typedef struct
     VALUE bound_values;
 } statement_bind_context;
 
+typedef enum {
+    bind_target_kind_statement,
+    bind_target_kind_collection
+} statement_bind_target_kind;
+
+// Where a value is bound to: a named parameter of a statement, or an
+// element of a collection being built. Keeps the type switch in
+// statement_bind_value single so that top-level columns and collection
+// elements always support exactly the same scalar types.
+typedef struct
+{
+    statement_bind_target_kind kind;
+    union {
+        struct {
+            CassStatement *statement;
+            const char *name;
+        } statement;
+        CassCollection *collection;
+    } as;
+} statement_bind_target;
+
+static CassError bind_target_int8(statement_bind_target *target, cass_int8_t value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_int8_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_int8(target->as.collection, value);
+}
+
+static CassError bind_target_int16(statement_bind_target *target, cass_int16_t value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_int16_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_int16(target->as.collection, value);
+}
+
+static CassError bind_target_int32(statement_bind_target *target, cass_int32_t value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_int32_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_int32(target->as.collection, value);
+}
+
+static CassError bind_target_int64(statement_bind_target *target, cass_int64_t value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_int64_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_int64(target->as.collection, value);
+}
+
+static CassError bind_target_float(statement_bind_target *target, cass_float_t value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_float_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_float(target->as.collection, value);
+}
+
+static CassError bind_target_double(statement_bind_target *target, cass_double_t value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_double_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_double(target->as.collection, value);
+}
+
+static CassError bind_target_bool(statement_bind_target *target, cass_bool_t value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_bool_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_bool(target->as.collection, value);
+}
+
+static CassError bind_target_string(statement_bind_target *target, const char *value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_string_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_string(target->as.collection, value);
+}
+
+static CassError bind_target_uuid(statement_bind_target *target, CassUuid value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_uuid_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_uuid(target->as.collection, value);
+}
+
+static CassError bind_target_collection(statement_bind_target *target, const CassCollection *value)
+{
+    if (target->kind == bind_target_kind_statement) {
+        return cass_statement_bind_collection_by_name(target->as.statement.statement, target->as.statement.name, value);
+    }
+    return cass_collection_append_collection(target->as.collection, value);
+}
+
 void statement_default_config(CassandraStatement *cassandra_statement)
 {
     cassandra_statement->bound_values = Qnil;
@@ -32,28 +133,32 @@ void statement_default_config(CassandraStatement *cassandra_statement)
     cass_statement_set_paging_size(cassandra_statement->statement, DEFAULT_PAGE_SIZE);
 }
 
-static int hash_cb(VALUE key, VALUE value, VALUE arg)
-{
-    statement_bind_context *ctx = (statement_bind_context *)arg;
-    const CassDataType* data_type;
-    CassValueType value_type;
-    CassError result;
-    const char *name;
+static void statement_bind_value(statement_bind_target *target, const CassDataType *data_type,
+                                 VALUE value, VALUE key, const char *role);
+static void statement_bind_collection(statement_bind_target *target, const CassDataType *data_type,
+                                      VALUE value, VALUE key);
 
-    if (SYMBOL_P(key)) {
-        key = rb_sym2str(key);
+static void statement_bind_check(CassError result, VALUE key)
+{
+    if (result != CASS_OK) {
+        rb_raise(eStatementError, "Failed to bind value of %"PRIsVALUE" column: %s", key, cass_error_desc(result));
     }
-    name = StringValueCStr(key);
+}
 
-    data_type = cass_prepared_parameter_data_type_by_name(ctx->prepared, name);
-    if (data_type == NULL) {
-        rb_raise(eStatementError, "Invalid name %s was given.", name);
-    }
-    value_type = cass_data_type_type(data_type);
+static void statement_bind_value(statement_bind_target *target, const CassDataType *data_type,
+                                 VALUE value, VALUE key, const char *role)
+{
+    const CassValueType value_type = cass_data_type_type(data_type);
+    CassError result;
 
     if (NIL_P(value)) {
-        result = cass_statement_bind_null_by_name(ctx->statement, name);
-        goto result_check;
+        if (target->kind == bind_target_kind_collection) {
+            // The driver has no cass_collection_append_null: Cassandra
+            // collections cannot contain null elements.
+            rb_raise(rb_eTypeError, "nil is not allowed as a collection %s in %"PRIsVALUE"", role, key);
+        }
+        statement_bind_check(cass_statement_bind_null_by_name(target->as.statement.statement, target->as.statement.name), key);
+        return;
     }
 
     switch (value_type) {
@@ -64,7 +169,7 @@ static int hash_cb(VALUE key, VALUE value, VALUE arg)
             if (v < INT8_MIN || v > INT8_MAX) {
                 rb_raise(rb_eRangeError, "Invalid value: %ld", v);
             }
-            result = cass_statement_bind_int8_by_name(ctx->statement, name, (cass_int8_t)v);
+            result = bind_target_int8(target, (cass_int8_t)v);
         }
         break;
 
@@ -76,7 +181,7 @@ static int hash_cb(VALUE key, VALUE value, VALUE arg)
                 rb_raise(rb_eRangeError, "Invalid value: %ld", v);
             }
 
-            result = cass_statement_bind_int16_by_name(ctx->statement, name, (cass_int16_t)v);
+            result = bind_target_int16(target, (cass_int16_t)v);
         }
         break;
 
@@ -88,12 +193,12 @@ static int hash_cb(VALUE key, VALUE value, VALUE arg)
                 rb_raise(rb_eRangeError, "Invalid value: %ld", v);
             }
 
-            result = cass_statement_bind_int32_by_name(ctx->statement, name, (cass_int32_t)v);
+            result = bind_target_int32(target, (cass_int32_t)v);
         }
         break;
 
     case CASS_VALUE_TYPE_BIGINT:
-        result = cass_statement_bind_int64_by_name(ctx->statement, name, NUM2LONG(value));
+        result = bind_target_int64(target, NUM2LONG(value));
         break;
 
     case CASS_VALUE_TYPE_FLOAT:
@@ -104,25 +209,27 @@ static int hash_cb(VALUE key, VALUE value, VALUE arg)
                 rb_raise(rb_eRangeError, "Invalid value: %lf", v);
             }
 
-            result = cass_statement_bind_float_by_name(ctx->statement, name, v);
+            result = bind_target_float(target, v);
         }
         break;
 
     case CASS_VALUE_TYPE_DOUBLE:
-        result = cass_statement_bind_double_by_name(ctx->statement, name, NUM2DBL(value));
+        result = bind_target_double(target, NUM2DBL(value));
         break;
 
     case CASS_VALUE_TYPE_BOOLEAN:
-        {
-            cass_bool_t v = RTEST(value) ? cass_true : cass_false;
-            result = cass_statement_bind_bool_by_name(ctx->statement, name, v);
-        }
+        result = bind_target_bool(target, RTEST(value) ? cass_true : cass_false);
         break;
 
     case CASS_VALUE_TYPE_TEXT:
     case CASS_VALUE_TYPE_ASCII:
     case CASS_VALUE_TYPE_VARCHAR:
-        result = cass_statement_bind_string_by_name(ctx->statement, name, StringValueCStr(value));
+        if (SYMBOL_P(value)) {
+            // rb_sym2str returns the Symbol's fstring; no allocation, so
+            // converting on every execution is fine.
+            value = rb_sym2str(value);
+        }
+        result = bind_target_string(target, StringValueCStr(value));
         break;
 
     case CASS_VALUE_TYPE_TIMESTAMP:
@@ -133,7 +240,7 @@ static int hash_cb(VALUE key, VALUE value, VALUE arg)
                 rb_raise(rb_eTypeError, "no implicit conversion of %"PRIsVALUE" to Time", rb_obj_class(value));
             }
         }
-        result = cass_statement_bind_int64_by_name(ctx->statement, name, (cass_int64_t)(NUM2DBL(rb_Float(value)) * 1000));
+        result = bind_target_int64(target, (cass_int64_t)(NUM2DBL(rb_Float(value)) * 1000));
         break;
 
     case CASS_VALUE_TYPE_UUID:
@@ -143,28 +250,255 @@ static int hash_cb(VALUE key, VALUE value, VALUE arg)
 
             result = cass_uuid_from_string(uuid_string, &uuid);
             if (result != CASS_OK) {
-                rb_raise(eStatementError, "Invalid UUID was given: %s=%"PRIsVALUE"", name, value);
+                rb_raise(eStatementError, "Invalid UUID was given: %"PRIsVALUE"=%"PRIsVALUE"", key, value);
             }
 
-            result = cass_statement_bind_uuid_by_name(ctx->statement, name, uuid);
+            result = bind_target_uuid(target, uuid);
         }
         break;
 
+    case CASS_VALUE_TYPE_LIST:
+    case CASS_VALUE_TYPE_SET:
+    case CASS_VALUE_TYPE_MAP:
+        statement_bind_collection(target, data_type, value, key);
+        return;
+
     default:
-        rb_raise(rb_eTypeError, "Unsupported %"PRIsVALUE" type: %s=%"PRIsVALUE"", rb_obj_class(value), name, value);
+        rb_raise(rb_eTypeError, "Unsupported %"PRIsVALUE" type: %"PRIsVALUE"=%"PRIsVALUE"", rb_obj_class(value), key, value);
     }
 
-result_check:
-    if (result != CASS_OK) {
-        rb_raise(eStatementError, "Failed to bind value: %s", cass_error_desc(result));
+    statement_bind_check(result, key);
+}
+
+typedef struct
+{
+    statement_bind_target target;
+    const CassDataType *data_type;
+    VALUE value;
+    VALUE key;
+} statement_bind_collection_args;
+
+struct statement_bind_map_ctx {
+    statement_bind_target *target;
+    const CassDataType *key_type;
+    const CassDataType *value_type;
+    VALUE key;
+};
+
+static int statement_bind_map_cb(VALUE k, VALUE v, VALUE arg)
+{
+    struct statement_bind_map_ctx *ctx = (struct statement_bind_map_ctx *)arg;
+
+    // A map is appended as alternating key, value pairs.
+    statement_bind_value(ctx->target, ctx->key_type, k, ctx->key, "key");
+    statement_bind_value(ctx->target, ctx->value_type, v, ctx->key, "value");
+    return ST_CONTINUE;
+}
+
+static VALUE statement_bind_collection_body(VALUE arg)
+{
+    statement_bind_collection_args *args = (statement_bind_collection_args *)arg;
+
+    if (cass_data_type_type(args->data_type) == CASS_VALUE_TYPE_MAP) {
+        struct statement_bind_map_ctx ctx;
+
+        ctx.target = &args->target;
+        ctx.key_type = cass_data_type_sub_data_type(args->data_type, 0);
+        ctx.value_type = cass_data_type_sub_data_type(args->data_type, 1);
+        ctx.key = args->key;
+        rb_hash_foreach(args->value, statement_bind_map_cb, (VALUE)&ctx);
+    } else {
+        const CassDataType *element_type = cass_data_type_sub_data_type(args->data_type, 0);
+        long length = RARRAY_LEN(args->value);
+
+        for (long i = 0; i < length; i++) {
+            statement_bind_value(&args->target, element_type, RARRAY_AREF(args->value, i), args->key, "element");
+        }
     }
+    return Qnil;
+}
 
-    if (!NIL_P(ctx->bound_values)) {
+/*
+ * Builds a CassCollection from a snapshotted (frozen) Array or Hash and binds
+ * it to the target. The value is guaranteed to be an Array (list/set) or Hash
+ * (map) because statement_snapshot_value normalizes it in Statement#bind
+ * before the first statement_bind_value call, and executions only replay
+ * values stored in bound_values.
+ */
+static void statement_bind_collection(statement_bind_target *target, const CassDataType *data_type,
+                                      VALUE value, VALUE key)
+{
+    const CassValueType type = cass_data_type_type(data_type);
+    statement_bind_collection_args args;
+    CassCollection *collection;
+    size_t item_count;
+    CassError result;
+    int state = 0;
+
+    if (type == CASS_VALUE_TYPE_MAP) {
+        if (cass_data_type_sub_type_count(data_type) != 2) {
+            rb_raise(eStatementError, "Invalid map type of %"PRIsVALUE" column", key);
+        }
+        Check_Type(value, T_HASH);
+        item_count = (size_t)RHASH_SIZE(value);
+    } else {
+        if (cass_data_type_sub_type_count(data_type) != 1) {
+            rb_raise(eStatementError, "Invalid collection type of %"PRIsVALUE" column", key);
+        }
+        Check_Type(value, T_ARRAY);
+        item_count = (size_t)RARRAY_LEN(value);
+    }
+
+    // cass_collection_new_from_data_type (not cass_collection_new) so that
+    // nested element types are propagated to the driver.
+    collection = cass_collection_new_from_data_type(data_type, item_count);
+    if (collection == NULL) {
+        rb_raise(eStatementError, "Failed to create a collection for %"PRIsVALUE" column", key);
+    }
+
+    args.target.kind = bind_target_kind_collection;
+    args.target.as.collection = collection;
+    args.data_type = data_type;
+    args.value = value;
+    args.key = key;
+
+    rb_protect(statement_bind_collection_body, (VALUE)&args, &state);
+    if (state) {
+        cass_collection_free(collection);
+        rb_jump_tag(state);
+    }
+
+    result = bind_target_collection(target, collection);
+    cass_collection_free(collection);
+    statement_bind_check(result, key);
+}
+
+static VALUE statement_snapshot_value(const CassDataType *data_type, VALUE value);
+
+struct statement_snapshot_map_ctx {
+    const CassDataType *key_type;
+    const CassDataType *value_type;
+    VALUE snapshot;
+};
+
+static int statement_snapshot_map_cb(VALUE k, VALUE v, VALUE arg)
+{
+    struct statement_snapshot_map_ctx *ctx = (struct statement_snapshot_map_ctx *)arg;
+
+    rb_hash_aset(ctx->snapshot,
+                 statement_snapshot_value(ctx->key_type, k),
+                 statement_snapshot_value(ctx->value_type, v));
+    return ST_CONTINUE;
+}
+
+/*
+ * Returns a deep-frozen snapshot of the value so a later in-place mutation by
+ * the caller (or another thread) doesn't change what gets bound at execution
+ * time. Executions then only walk frozen containers, which makes re-binding
+ * on execute safe without re-validating.
+ */
+static VALUE statement_snapshot_value(const CassDataType *data_type, VALUE value)
+{
+    if (NIL_P(value)) {
+        return Qnil;
+    }
+
+    switch (cass_data_type_type(data_type)) {
+    case CASS_VALUE_TYPE_LIST:
+    case CASS_VALUE_TYPE_SET:
+        {
+            const CassDataType *element_type = cass_data_type_sub_data_type(data_type, 0);
+            VALUE array;
+            VALUE snapshot;
+            long length;
+
+            if (element_type == NULL) {
+                rb_raise(eStatementError, "Invalid collection type: missing element type");
+            }
+
+            if (RB_TYPE_P(value, T_ARRAY)) {
+                array = value;
+            } else if (rb_obj_is_kind_of(value, cSet)) {
+                array = rb_funcall(value, id_to_a, 0);
+                // A Set subclass may override to_a to return anything.
+                Check_Type(array, T_ARRAY);
+            } else {
+                rb_raise(rb_eTypeError, "no implicit conversion of %"PRIsVALUE" into Array or Set", rb_obj_class(value));
+            }
+
+            length = RARRAY_LEN(array);
+            snapshot = rb_ary_new_capa(length);
+            for (long i = 0; i < length; i++) {
+                rb_ary_push(snapshot, statement_snapshot_value(element_type, RARRAY_AREF(array, i)));
+            }
+            return rb_ary_freeze(snapshot);
+        }
+
+    case CASS_VALUE_TYPE_MAP:
+        {
+            struct statement_snapshot_map_ctx ctx;
+
+            Check_Type(value, T_HASH);
+            ctx.key_type = cass_data_type_sub_data_type(data_type, 0);
+            ctx.value_type = cass_data_type_sub_data_type(data_type, 1);
+            if (ctx.key_type == NULL || ctx.value_type == NULL) {
+                rb_raise(eStatementError, "Invalid collection type: missing map key or value type");
+            }
+            ctx.snapshot = rb_hash_new();
+            rb_hash_foreach(value, statement_snapshot_map_cb, (VALUE)&ctx);
+            return rb_hash_freeze(ctx.snapshot);
+        }
+
+    case CASS_VALUE_TYPE_TEXT:
+    case CASS_VALUE_TYPE_ASCII:
+    case CASS_VALUE_TYPE_VARCHAR:
+        if (SYMBOL_P(value)) {
+            // Symbols are immutable; no defensive copy needed.
+            return value;
+        }
+        // Also converts to_str objects here so the converted String (not the
+        // possibly mutable object) is what gets stored and re-bound.
+        StringValue(value);
+        return rb_str_new_frozen(value);
+
+    default:
         if (RB_TYPE_P(value, T_STRING)) {
-            // Snapshot the value so a later in-place mutation by the caller
-            // doesn't change what gets bound at execution time.
-            value = rb_str_new_frozen(value);
+            return rb_str_new_frozen(value);
         }
+        return value;
+    }
+}
+
+static int hash_cb(VALUE key, VALUE value, VALUE arg)
+{
+    statement_bind_context *ctx = (statement_bind_context *)arg;
+    const CassDataType* data_type;
+    const char *name;
+    statement_bind_target target;
+
+    if (SYMBOL_P(key)) {
+        key = rb_sym2str(key);
+    }
+    name = StringValueCStr(key);
+
+    data_type = cass_prepared_parameter_data_type_by_name(ctx->prepared, name);
+    if (data_type == NULL) {
+        rb_raise(eStatementError, "Invalid name %s was given.", name);
+    }
+
+    target.kind = bind_target_kind_statement;
+    target.as.statement.statement = ctx->statement;
+    target.as.statement.name = name;
+
+    if (!NIL_P(ctx->bound_values)) {
+        // Snapshot before binding so the value bound now and the value
+        // replayed by later executions are the same deep-frozen object.
+        value = statement_snapshot_value(data_type, value);
+    }
+
+    statement_bind_value(&target, data_type, value, key, NULL);
+
+    if (!NIL_P(ctx->bound_values)) {
         rb_hash_aset(ctx->bound_values, key, value);
     }
 

data/ilios.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = 'Cassandra driver written by C language'
   spec.homepage = 'https://github.com/Watson1978/ilios'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.4.0'
 
   spec.requirements << 'cmake'
 

data/lib/ilios/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Ilios
-  VERSION = '1.0.6'
+  VERSION = '1.1.0'
   public_constant :VERSION
 
   CASSANDRA_CPP_DRIVER_VERSION = '2.17.1'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ilios
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.1.0
 platform: ruby
 authors:
 - Watson
@@ -58,7 +58,7 @@ metadata:
   homepage_uri: https://github.com/Watson1978/ilios
   source_code_uri: https://github.com/Watson1978/ilios
   bug_tracker_uri: https://github.com/Watson1978/ilios/issues
-  documentation_uri: https://www.rubydoc.info/gems/ilios/1.0.6
+  documentation_uri: https://www.rubydoc.info/gems/ilios/1.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -67,7 +67,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - cmake
-rubygems_version: 4.0.16
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Cassandra driver written by C language
 test_files: []