ilios 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18d160f81c3298017c1e7936a32b3c3668414ebc1c327c59ef24c4ad741aa16a
-  data.tar.gz: d664a164d230db6deea79bdf8f80ad6e2225da9f31640a84868a4b6d4a91062f
+  metadata.gz: e2e5ed874d686d5d019f339dd5123277d70000429fc0e09d3ea6ad589a0d380b
+  data.tar.gz: f4618e513dcabbcde12f697c71ea565f3e9b6a398b3424af7970d173fbf8698b
 SHA512:
-  metadata.gz: 8d3634a3a2fab8cf35f514cde6fc741f37fb4aa876d8f96cf277d18e90606c5e52682b32731ffd0347bd7666a04df7496d486a0a7861fc189b622b175b2dce0a
-  data.tar.gz: fd1e720c2b4dabe04b973a5db48d993188b630d6ec476bb22710062e11aed5e4fdb42245513b970f9b31508893be13dfa577d30527cb7748c5ccd1368a1c3b9f
+  metadata.gz: 2beb63c0e1e259e2127cdf9652985868a704ee42b2bc66d0ac54e6eb2545b22ccebc392755de048c7fa3c4148164aa09a276a4ec4876671bc6779f576b8330d6
+  data.tar.gz: 5a48c0c82277ef5960ed4859d50709e986f324c471e3525b0e80cce5a64967071389a2927f6bad772fde986205e9d5e200ecd5deb4be5778ff138283206547e3

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+lib/**/*.rb
+ext/**/*.c
+*.md
+LICENSE

data/README.md

@@ -29,6 +29,8 @@ WITH REPLICATION = {
 };
 ```
 
+Then, you can run the following code.
+
 ```ruby
 require 'ilios'
 
@@ -107,20 +109,29 @@ prepare_future = Ilios::Cassandra.session.prepare_async(<<~CQL)
 CQL
 
 prepare_future.on_success { |statement|
-  statement.bind({
-    id: 1,
-    message: 'Hello World',
-    created_at: Time.now,
-  })
-  result_future = Ilios::Cassandra.session.execute_async(statement)
-  result_future.on_success { |result|
-    p result
-    p "success"
-  }
-  result_future.on_failure {
-    p "fail"
-  }
+  futures = []
+
+  10.times do |i|
+    statement.bind({
+      id: i,
+      message: 'Hello World',
+      created_at: Time.now,
+    })
+    result_future = Ilios::Cassandra.session.execute_async(statement)
+    result_future.on_success { |result|
+      p result
+      p "success"
+    }
+    result_future.on_failure {
+      p "fail"
+    }
+
+    futures << result_future
+  end
+  futures.each(&:await)
 }
+
+prepare_future.await
 ```
 
 ## Contributing

data/ext/ilios/cassandra.c

@@ -1,5 +1,12 @@
 #include "ilios.h"
 
+/**
+ * Connects a session to the keyspace specified in +config+ method.
+ *
+ * @return [Cassandra::Session] A new session object.
+ * @raise [RuntimeError] If no host is specified to connect in +config+ method.
+ * @raise [Cassandra::ConnectError] If the connection fails for any reason.
+ */
 static VALUE cassandra_connect(VALUE self)
 {
     CassandraSession *cassandra_session;

data/ext/ilios/future.c

@@ -34,6 +34,7 @@ static void future_thread_pool_init(future_thread_pool *pool)
     pool->queue = rb_funcall(cQueue, id_new, 0);
     for (int i = 0; i < THREAD_MAX; i++) {
         pool->thread[i] = rb_thread_create(future_result_yielder_thread, (void*)pool);
+        rb_funcall(pool->thread[i], id_abort_on_exception_set, 1, Qtrue);
     }
 }
 
@@ -112,11 +113,11 @@ static void future_result_failure_yield(CassandraFuture *cassandra_future)
     }
 }
 
-static VALUE future_result_yielder_synchronize(VALUE arg)
+static VALUE future_result_yielder_synchronize(VALUE future)
 {
     CassandraFuture *cassandra_future;
 
-    GET_FUTURE(arg, cassandra_future);
+    GET_FUTURE(future, cassandra_future);
 
     if (cass_future_error_code(cassandra_future->future) == CASS_OK) {
         future_result_success_yield(cassandra_future);
@@ -126,14 +127,29 @@ static VALUE future_result_yielder_synchronize(VALUE arg)
     return Qnil;
 }
 
-static VALUE future_result_yielder(VALUE arg)
+static VALUE future_result_yielder_body(VALUE future)
 {
     CassandraFuture *cassandra_future;
 
-    GET_FUTURE(arg, cassandra_future);
+    GET_FUTURE(future, cassandra_future);
 
     nogvl_future_wait(cassandra_future->future);
-    return rb_mutex_synchronize(cassandra_future->proc_mutex, future_result_yielder_synchronize, arg);
+    return rb_mutex_synchronize(cassandra_future->proc_mutex, future_result_yielder_synchronize, future);
+
+}
+
+static VALUE future_result_yielder_ensure(VALUE future)
+{
+    CassandraFuture *cassandra_future;
+
+    GET_FUTURE(future, cassandra_future);
+    uv_sem_post(&cassandra_future->sem);
+    return Qnil;
+}
+
+static VALUE future_result_yielder(VALUE future)
+{
+    return rb_ensure(future_result_yielder_body, future, future_result_yielder_ensure, future);
 }
 
 static VALUE future_result_yielder_thread(void *arg)
@@ -147,6 +163,32 @@ static VALUE future_result_yielder_thread(void *arg)
     return Qnil;
 }
 
+VALUE future_create(CassFuture *future, VALUE session, future_kind kind)
+{
+    CassandraFuture *cassandra_future;
+    VALUE cassandra_future_obj;
+
+    cassandra_future_obj = CREATE_FUTURE(cassandra_future);
+    cassandra_future->kind = kind;
+    cassandra_future->future = future;
+    cassandra_future->session_obj = session;
+    cassandra_future->proc_mutex = rb_mutex_new();
+    uv_sem_init(&cassandra_future->sem, 0);
+    cassandra_future->already_waited = false;
+
+    return cassandra_future_obj;
+}
+
+/**
+ * Run block when future resolves to a value.
+ *
+ * @yieldparam value [Cassandra::Statement, Cassandra::Result] A value.
+ *   Yields +Cassandra::Statement+ object when future was created by +Cassandra::Session#prepare_async+.
+ *   Yields +Cassandra::Result+ object when future was created by +Cassandra::Session#execute_async+.
+ * @return [Cassandra::Future] self.
+ * @raise [Cassandra::ExecutionError] If this method will be called twice.
+ * @raise [ArgumentError] If no block was given.
+ */
 static VALUE future_on_success(VALUE self)
 {
     CassandraFuture *cassandra_future;
@@ -157,33 +199,34 @@ static VALUE future_on_success(VALUE self)
     if (cassandra_future->on_success_block) {
         rb_raise(eExecutionError, "It should not call twice");
     }
+    if (!rb_block_given_p()) {
+        rb_raise(rb_eArgError, "no block given");
+    }
 
-    if (rb_block_given_p()) {
-        rb_mutex_lock(cassandra_future->proc_mutex);
-
-        if (!cassandra_future->on_failure_block) {
-            // Invoke the callback with thread pool only once
-            wakeup_thread = true;
-        }
+    rb_mutex_lock(cassandra_future->proc_mutex);
 
-        cassandra_future->on_success_block = rb_block_proc();
+    if (!cassandra_future->on_failure_block) {
+        // Invoke the callback with thread pool only once
+        wakeup_thread = true;
+    }
 
-        if (cass_future_ready(cassandra_future->future)) {
-            rb_mutex_unlock(cassandra_future->proc_mutex);
-            if (cass_future_error_code(cassandra_future->future) == CASS_OK) {
-                future_result_success_yield(cassandra_future);
-            }
-            return self;
-        }
+    cassandra_future->on_success_block = rb_block_proc();
 
-        if (wakeup_thread) {
-            future_queue_push(future_thread_pool_get(cassandra_future), self);
-        }
-        rb_mutex_unlock(cassandra_future->proc_mutex);
+    if (wakeup_thread) {
+        future_queue_push(future_thread_pool_get(cassandra_future), self);
     }
+    rb_mutex_unlock(cassandra_future->proc_mutex);
+
     return self;
 }
 
+/**
+ * Run block when future resolves to error.
+ *
+ * @return [Cassandra::Future] self.
+ * @raise [Cassandra::ExecutionError] If this method will be called twice.
+ * @raise [ArgumentError] If no block was given.
+ */
 static VALUE future_on_failure(VALUE self)
 {
     CassandraFuture *cassandra_future;
@@ -194,30 +237,48 @@ static VALUE future_on_failure(VALUE self)
     if (cassandra_future->on_failure_block) {
         rb_raise(eExecutionError, "It should not call twice");
     }
+    if (!rb_block_given_p()) {
+        rb_raise(rb_eArgError, "no block given");
+    }
 
-    if (rb_block_given_p()) {
-        rb_mutex_lock(cassandra_future->proc_mutex);
+    rb_mutex_lock(cassandra_future->proc_mutex);
 
-        if (!cassandra_future->on_success_block) {
-            // Invoke the callback with thread pool only once
-            wakeup_thread = true;
-        }
+    if (!cassandra_future->on_success_block) {
+        // Invoke the callback with thread pool only once
+        wakeup_thread = true;
+    }
 
-        cassandra_future->on_failure_block = rb_block_proc();
+    cassandra_future->on_failure_block = rb_block_proc();
 
-        if (cass_future_ready(cassandra_future->future)) {
-            rb_mutex_unlock(cassandra_future->proc_mutex);
-            if (cass_future_error_code(cassandra_future->future) != CASS_OK) {
-                future_result_failure_yield(cassandra_future);
-            }
-            return self;
-        }
+    if (wakeup_thread) {
+        future_queue_push(future_thread_pool_get(cassandra_future), self);
+    }
+    rb_mutex_unlock(cassandra_future->proc_mutex);
 
-        if (wakeup_thread) {
-            future_queue_push(future_thread_pool_get(cassandra_future), self);
-        }
-        rb_mutex_unlock(cassandra_future->proc_mutex);
+    return self;
+}
+
+/**
+ * Wait to complete a future's statement.
+ *
+ * @return [Cassandra::Future] self.
+ */
+static VALUE future_await(VALUE self)
+{
+    CassandraFuture *cassandra_future;
+
+    GET_FUTURE(self, cassandra_future);
+
+    if (cassandra_future->already_waited) {
+        rb_raise(eExecutionError, "It should not call twice");
+    }
+
+    if (cassandra_future->on_success_block || cassandra_future->on_failure_block) {
+        nogvl_sem_wait(&cassandra_future->sem);
+    } else {
+        nogvl_future_wait(cassandra_future->future);
     }
+    cassandra_future->already_waited = true;
     return self;
 }
 
@@ -238,6 +299,7 @@ static void future_destroy(void *ptr)
     if (cassandra_future->future) {
         cass_future_free(cassandra_future->future);
     }
+    uv_sem_destroy(&cassandra_future->sem);
     xfree(cassandra_future);
 }
 
@@ -263,6 +325,7 @@ void Init_future(void)
 
     rb_define_method(cFuture, "on_success", future_on_success, 0);
     rb_define_method(cFuture, "on_failure", future_on_failure, 0);
+    rb_define_method(cFuture, "await", future_await, 0);
 
     future_thread_pool_init(&thread_pool_prepare);
     future_thread_pool_init(&thread_pool_execute);

data/ext/ilios/ilios.h

@@ -54,6 +54,9 @@ typedef struct
     VALUE on_success_block;
     VALUE on_failure_block;
     VALUE proc_mutex;
+
+    uv_sem_t sem;
+    bool already_waited;
 } CassandraFuture;
 
 extern const rb_data_type_t cassandra_session_data_type;
@@ -94,9 +97,11 @@ extern void Init_statement(void);
 extern void Init_result(void);
 extern void Init_future(void);
 
+extern VALUE future_create(CassFuture *future, VALUE session, future_kind kind);
 extern void nogvl_future_wait(CassFuture *future);
 extern CassFuture *nogvl_session_prepare(CassSession* session, VALUE query);
 extern CassFuture *nogvl_session_execute(CassSession* session, CassStatement* statement);
+extern void nogvl_sem_wait(uv_sem_t *sem);
 
 extern void statement_default_config(CassandraStatement *cassandra_statement);
 extern void result_await(CassandraResult *cassandra_result);

data/ext/ilios/nogvl.c

@@ -51,3 +51,16 @@ CassFuture *nogvl_session_execute(CassSession* session, CassStatement* statement
     nogvl_session_execute_args args = { session, statement };
     return (CassFuture *)rb_thread_call_without_gvl(nogvl_session_execute_cb, &args, RUBY_UBF_PROCESS, 0);
 }
+
+static void *nogvl_sem_wait_cb(void *ptr)
+{
+    uv_sem_t *sem = (uv_sem_t *)ptr;
+    uv_sem_wait(sem);
+    return NULL;
+}
+
+void nogvl_sem_wait(uv_sem_t *sem)
+{
+    // Releases GVL to run another thread while waiting
+    rb_thread_call_without_gvl(nogvl_sem_wait_cb, sem, RUBY_UBF_PROCESS, 0);
+}

data/ext/ilios/result.c

@@ -33,6 +33,12 @@ void result_await(CassandraResult *cassandra_result)
     }
 }
 
+/**
+ * Loads next page synchronously
+ *
+ * @return [Cassandra::Result, nil] returns self or +nil+ if last page.
+ * @raise [Cassandra::ExecutionError] If the query is invalid or there is something wrong with the session.
+ */
 static VALUE result_next_page(VALUE self)
 {
     CassandraResult *cassandra_result;
@@ -176,23 +182,49 @@ static VALUE result_convert_row(const CassResult *result, const CassRow *row, si
     return hash;
 }
 
+struct result_each_arg {
+    CassandraResult *cassandra_result;
+    CassIterator *iterator;
+};
+
+static VALUE result_each_body(VALUE a)
+{
+    struct result_each_arg *args = (struct result_each_arg *)a;
+    size_t column_count = cass_result_column_count(args->cassandra_result->result);
+
+    while (cass_iterator_next(args->iterator)) {
+        const CassRow *row = cass_iterator_get_row(args->iterator);
+        rb_yield(result_convert_row(args->cassandra_result->result, row, column_count));
+    }
+    return Qnil;
+}
+
+static VALUE result_each_ensure(VALUE a)
+{
+    CassIterator *iterator = (CassIterator *)a;
+    cass_iterator_free(iterator);
+    return Qnil;
+}
+
+/**
+ * Yield the row of result into a block.
+ *
+ * @return [Cassandra::Result, Enumerator] returns self or +Enumerator+ if block is not given.
+ */
 static VALUE result_each(VALUE self)
 {
     CassandraResult *cassandra_result;
     CassIterator *iterator;
-    size_t column_count;
+    struct result_each_arg args;
 
     RETURN_ENUMERATOR(self, 0, 0);
 
     GET_RESULT(self, cassandra_result);
 
     iterator = cass_iterator_from_result(cassandra_result->result);
-    column_count = cass_result_column_count(cassandra_result->result);
-    while (cass_iterator_next(iterator)) {
-        const CassRow *row = cass_iterator_get_row(iterator);
-        rb_yield(result_convert_row(cassandra_result->result, row, column_count));
-    }
-    cass_iterator_free(iterator);
+    args.cassandra_result = cassandra_result;
+    args.iterator = iterator;
+    rb_ensure(result_each_body, (VALUE)&args, result_each_ensure, (VALUE)iterator);
 
     return self;
 }

data/ext/ilios/session.c

@@ -15,26 +15,32 @@ const rb_data_type_t cassandra_session_data_type = {
     RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED | RUBY_TYPED_FROZEN_SHAREABLE,
 };
 
+/**
+ * Prepares a given query asynchronously and returns a future prepared statement.
+ *
+ * @param query [String] A query to prepare.
+ * @return [Cassandra::Future] A future prepared statement.
+ * @raise [TypeError] If the query is not a string.
+ */
 static VALUE session_prepare_async(VALUE self, VALUE query)
 {
     CassandraSession *cassandra_session;
-    CassandraFuture *cassandra_future;
     CassFuture *prepare_future;
-    VALUE cassandra_future_obj;
 
     GET_SESSION(self, cassandra_session);
 
     prepare_future = nogvl_session_prepare(cassandra_session->session, query);
-
-    cassandra_future_obj = CREATE_FUTURE(cassandra_future);
-    cassandra_future->kind = prepare_async;
-    cassandra_future->future = prepare_future;
-    cassandra_future->session_obj = self;
-    cassandra_future->proc_mutex = rb_mutex_new();
-
-    return cassandra_future_obj;
+    return future_create(prepare_future, self, prepare_async);
 }
 
+/**
+ * Prepares a given query.
+ *
+ * @param query [String] A query to prepare.
+ * @return [Cassandra::Statement] A statement to execute.
+ * @raise [Cassandra::ExecutionError] If the query is invalid or there is something wrong with the session.
+ * @raise [TypeError] If the query is not a string.
+ */
 static VALUE session_prepare(VALUE self, VALUE query)
 {
     CassandraSession *cassandra_session;
@@ -66,29 +72,34 @@ static VALUE session_prepare(VALUE self, VALUE query)
     return cassandra_statement_obj;
 }
 
+/**
+ * Executes a given statement asynchronously and returns a future result.
+ *
+ * @param statement [Cassandra::Statement] A statement to execute.
+ * @return [Cassandra::Future] A future for result.
+ * @raise [TypeError] If the invalid object is given.
+ */
 static VALUE session_execute_async(VALUE self, VALUE statement)
 {
     CassandraSession *cassandra_session;
     CassandraStatement *cassandra_statement;
-    CassandraFuture *cassandra_future;
     CassFuture *result_future;
-    VALUE cassandra_future_obj;
 
     GET_SESSION(self, cassandra_session);
     GET_STATEMENT(statement, cassandra_statement);
 
     result_future = nogvl_session_execute(cassandra_session->session, cassandra_statement->statement);
-
-    cassandra_future_obj = CREATE_FUTURE(cassandra_future);
-    cassandra_future->kind = execute_async;
-    cassandra_future->future = result_future;
-    cassandra_future->session_obj = self;
-    cassandra_future->statement_obj = statement;
-    cassandra_future->proc_mutex = rb_mutex_new();
-
-    return cassandra_future_obj;
+    return future_create(result_future, self, execute_async);
 }
 
+/**
+ * Executes a given statement.
+ *
+ * @param statement [Cassandra::Statement] A statement to execute.
+ * @return [Cassandra::Result] A result.
+ * @raise [Cassandra::ExecutionError] If there is something wrong with the session.
+ * @raise [TypeError] If the invalid object is given.
+ */
 static VALUE session_execute(VALUE self, VALUE statement)
 {
     CassandraSession *cassandra_session;
@@ -115,9 +126,6 @@ static void session_destroy(void *ptr)
     CassandraSession *cassandra_session = (CassandraSession *)ptr;
 
     if (cassandra_session->session) {
-        CassFuture *close_future = cass_session_close(cassandra_session->session);
-        nogvl_future_wait(close_future);
-        cass_future_free(close_future);
         cass_session_free(cassandra_session->session);
     }
     if (cassandra_session->connect_future) {

data/ext/ilios/statement.c

@@ -150,6 +150,16 @@ result_check:
     return ST_CONTINUE;
 }
 
+/**
+ * Binds a specified column value to a query.
+ * A hash object should be given with column name as key.
+ *
+ * @param hash [Hash] A hash object to bind.
+ * @return [Cassandra::Statement] self.
+ * @raise [RangeError] If an invalid range of values was given.
+ * @raise [TypeError] If an invalid type of values was given.
+ * @raise [Cassandra::StatementError] If an invalid column name was given.
+ */
 static VALUE statement_bind(VALUE self, VALUE hash)
 {
     CassandraStatement *cassandra_statement;
@@ -161,6 +171,12 @@ static VALUE statement_bind(VALUE self, VALUE hash)
     return self;
 }
 
+/**
+ * Sets the statement's page size.
+ *
+ * @param page_size [Integer] A page size.
+ * @return [Cassandra::Statement] self.
+ */
 static VALUE statement_page_size(VALUE self, VALUE page_size)
 {
     CassandraStatement *cassandra_statement;

data/ilios.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.files =
     Dir.chdir(__dir__) do
       `git ls-files -z`.split("\x0").reject do |f|
-        (f == __FILE__) || f.match(%r{\A(?:(?:test)/|\.(?:git|editorconfig|rubocop.*))})
+        (f == __FILE__) || f.match(%r{\A(?:(?:test|example)/|\.(?:git|editorconfig|rubocop.*))})
       end
     end
   spec.require_paths = ['lib']

data/lib/ilios/version.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Ilios
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
   public_constant :VERSION
 
-  CASSANDRA_CPP_DRIVER_VERSION = '2.17.0'
+  CASSANDRA_CPP_DRIVER_VERSION = '2.17.1'
   public_constant :CASSANDRA_CPP_DRIVER_VERSION
 
-  LIBUV_VERSION = '1.46.0'
+  LIBUV_VERSION = '1.47.0'
   public_constant :LIBUV_VERSION
 end

data/lib/ilios.rb

@@ -5,6 +5,7 @@ require 'ilios/version'
 
 module Ilios
   module Cassandra
+    # The default options.
     @@config = {
       keyspace: 'ilios',
       hosts: ['127.0.0.1'],
@@ -14,10 +15,24 @@ module Ilios
       page_size: 10_000
     }
 
+    #
+    # Configures the option for connection or execution.
+    # The default value will be overridden by the specified option.
+    #
+    # @param config [Hash] A hash object contained the options.
+    #
     def self.config=(config)
       @@config = @@config.merge(config)
     end
 
+    #
+    # Connects a session to the keyspace specified in +config+ method.
+    # The session object will be memorized by each threads.
+    #
+    # @return [Cassandra::Session] The session object.
+    # @raise [RuntimeError] If no host is specified to connect in +config+ method.
+    # @raise [Cassandra::ConnectError] If the connection fails for any reason.
+    #
     def self.session
       Thread.current[:ilios_cassandra_session] ||= connect
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ilios
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Watson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-07 00:00:00.000000000 Z
+date: 2023-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_portile2
@@ -32,6 +32,7 @@ extensions:
 - ext/ilios/extconf.rb
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - Dockerfile
 - Gemfile
 - README.md