crystalruby 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 117525a6b5905a6c4aa86b0b2fed0c25e46d0e97b6de8ce187b90f1438394f19
-  data.tar.gz: 55b35d8731c2d7e68f6cb0a1a4ea3eb068805bc4297f1b85fceac08cb288682a
+  metadata.gz: eeae38802618342fade685584872134cd905229adfe493619130bf008c649390
+  data.tar.gz: ff35b13a1ff26f2aa42063a91ebfea888efd03ffd4fabb32911baf70557a3cdb
 SHA512:
-  metadata.gz: 585ad3697b06ba3660989ea538ddae90816d0e93a947e95ab5e6bb83ace64d35988c436cf8e07cad077529691baebbdbdeac6bcc0e7a991297d67f2efada5438
-  data.tar.gz: bd06431cc0c059481db8215676e493f16d485cb14a8b15dedc3de6e79df79716c4e6499bb4f9678257659601224b249798dc8c4c492c1659c46157714e45499e
+  metadata.gz: 43b28e5a1739a80ebe77064612fbf11024d9b6f7a9e3fd4357a0d3c6d99f90322953b34b484d7b8c010e40336fa1ba2d64bb4c59ec59bd0cef2ebaaea1fefd65
+  data.tar.gz: 70a9068038a5bc107ab6beb398491dd04cec70c2bf402dda35c80e70282033c2a1e7da482a15a0f378676835daee3eb220af66d02ab98a4d2be7991fb18d818d

data/README.md

@@ -258,7 +258,7 @@ E.g.
 
 IntArrOrBoolArr = crtype{ Array(Bool) | Array(Int32) }
 
-crystalize [a: IntArrOrBoolArr] => json{ IntArrOrBoolArr }
+crystalize [a: json{ IntArrOrBoolArr }] => json{ IntArrOrBoolArr }
 def method_with_named_types(a)
   return a
 end
@@ -273,16 +273,19 @@ Exceptions thrown in Crystal code can be caught in Ruby.
 You can use any Crystal shards and write ordinary, stand-alone Crystal code.
 
 The default entry point for the crystal shared library generated by the gem is
-inside `./crystalruby/src/main.cr`. This file is not automatically overridden by the gem, and is safe for you to define and require new files relative to this location to write additional stand-alone Crystal code.
+inside `./crystalruby/{library_name}/src/main.cr`.
+`{library_name}` defaults to `crystalruby` if you haven't explicitly specific a different library target.
 
-You can define shards inside `./crystalruby/src/shard.yml`
+This file is not automatically overridden by the gem, and is safe for you to define and require new files relative to this location to write additional stand-alone Crystal code.
+
+You can define shard dependencies inside `./crystalruby/{library_name}/src/shard.yml`
 Run the below to install new shards
 
 ```bash
 bundle exec crystalruby install
 ```
 
-Remember to require these installed shards after installing them. E.g. inside `./crystalruby/src/main.cr`
+Remember to also require these dependencies after installing them to make them available to `crystalruby` code. E.g. inside `./crystalruby/{libraryname}/src/main.cr`
 
 You can edit the default paths for crystal source and library files from within the `./crystalruby.yaml` config file.
 
@@ -309,7 +312,7 @@ MyModule.add("1", "2")
 
 ## Inline Chunks
 
-`crystalruby` also allows you to write inline Crystal code that does not require binding to Ruby. This can be useful for e.g. performing setup or teardown operations.
+`crystalruby` also allows you to write inline Crystal code that does not require binding to Ruby. This can be useful for e.g. performing setup operations or initializations.
 
 Follow these steps for a toy example of how we can use crystalized ruby and inline chunks to expose the [crystal-redis](https://github.com/stefanwille/crystal-redis) library to Ruby.
 
@@ -467,13 +470,13 @@ Then you can run this file as part of your build step, to ensure all Crystal cod
 
 ## Concurrency
 
-While Ruby programs allow multi-threading, Crystal by default uses only a single thread, while utilising Fiber based cooperative-multitasking to allow for concurrent execution. This means that by default, Crystal libraries can not safely be invoked in parallel across multiple Ruby threads.
+While Ruby programs allow multi-threading, Crystal (if not using experimental multi-thread support) uses only a single thread and utilises Fiber based cooperative-multitasking to allow for concurrent execution. This means that by default, Crystal libraries can not safely be invoked in parallel across multiple Ruby threads.
 
-To safely expose this behaviour, `crystalruby` implements a Reactor, which multiplexes all Ruby calls to Crystal across a single thread. This way you can safely use `crystalruby` in a multi-threaded Ruby environment.
+To safely utilise `crystalruby` in a multithreaded environment, `crystalruby` implements a Reactor, which multiplexes all Ruby calls to Crystal across a single thread.
 
-By default `crystalruby` methods are blocking/synchronous, this means that for blocking operations, a single crystalruby call can block the entire reactor.
+By default `crystalruby` methods are blocking/synchronous, this means that for blocking operations, a single crystalruby call can block the entire reactor across _all_ threads.
 
-To allow you to benefit from Crystal's fiber based concurrency, you can use the `async` option on crystalized ruby methods. This allows several Ruby threads to invoke Crystal code simultaneously.
+To allow you to benefit from Crystal's fiber based concurrency, you can use the `async: true` option on crystalized ruby methods. This allows several Ruby threads to invoke Crystal code simultaneously.
 
 E.g.
 
@@ -498,7 +501,7 @@ end
 
 ### Reactor performance
 
-There is a small amount of synchronization overhead to multiplexing calls across a single thread. Ad-hoc testing amounts this to be around 10 nanoseconds per call.
+There is a small amount of synchronization overhead to multiplexing calls across a single thread. Ad-hoc testing on a fast machine amounts this to be within the order of 10 nanoseconds per call.
 For most use-cases this overhead is negligible, especially if the bulk of your CPU heavy task occurs exclusively in Crystal code. However, if you are invoking very fast Crystal code from Ruby in a tight loop (e.g. a simple 1 + 2)
 then the overhead of the reactor can become significant.
 
@@ -517,9 +520,9 @@ recompile Crystal code only when it detects changes to the embedded function or
 
 ## Multi-library support
 
-Large Crystal projects are known to have long compile times. To mitigate this, `crystalruby` supports splitting your Crystal code into multiple libraries. This allows you to only recompile the library that has changed, rather than the entire project.
-To indicate which library a piece of embedded Crystal code belongs to, you can use the `library` option in the `crystalize` and `crystal` methods.
-If the "lib" option is not provided, the code will be compiled into the default library (simply named `crystalruby`).
+Large Crystal projects are known to have long compile times. To mitigate this, `crystalruby` supports splitting your Crystal code into multiple libraries. This allows you to only recompile any libraries that have changed, rather than all crystalcode within the entire project.
+To indicate which library a piece of embedded Crystal code belongs to, you can use the `lib` option in the `crystalize` and `crystal` methods.
+If the `lib` option is not provided, the code will be compiled into the default library (simply named `crystalruby`).
 
 ```ruby
 module Foo
@@ -534,12 +537,12 @@ module Foo
 end
 ```
 
-Naturally Crystal code must be in the same library to interact directly.
-Interaction across multiple libraries can be coordinated via Ruby code.
+Naturally, Crystal methods must reside in the same library to natively interact.
+Cross library interaction can be facilitated via Ruby code.
 
 ## Troubleshooting
 
-The logic to detect when to JIT recompile is not robust and can end up in an inconsistent state. To remedy this it is useful to clear out all generated assets and build from scratch.
+In cases where compiled assets are in left an invalid state, it can be useful to clear out generated assets and rebuild from scratch.
 
 To do this execute:
 

data/exe/crystalruby

@@ -36,6 +36,9 @@ def clean
   Dir["#{CrystalRuby.config.crystal_src_dir}/**/src/generated"].each do |codegen_dir|
     FileUtils.rm_rf(codegen_dir)
   end
+  Dir["#{CrystalRuby.config.crystal_src_dir}/**/lib"].each do |lib_dir|
+    FileUtils.rm_rf(lib_dir)
+  end
 end
 
 def build

data/lib/crystalruby/compilation.rb

@@ -1,4 +1,3 @@
-require "open3"
 require "tmpdir"
 require "shellwords"
 

data/lib/crystalruby/function.rb

@@ -6,7 +6,7 @@ module CrystalRuby
     include Typemaps
     include Config
 
-    attr_accessor :owner, :method_name, :args, :returns, :function_body, :lib, :async, :block
+    attr_accessor :owner, :method_name, :args, :returns, :function_body, :lib, :async, :block, :attached
 
     def initialize(method:, args:, returns:, function_body:, lib:, async: false, &block)
       self.owner = method.owner
@@ -17,12 +17,13 @@ module CrystalRuby
       self.lib = lib
       self.async = async
       self.block = block
+      self.attached = false
     end
 
     # This is where we write/overwrite the class and instance methods
     # with their crystalized equivalents.
     # We also perform JIT compilation and JIT attachment of the FFI functions.
-    # Crystalized methods work in a live-reloading manner environment.
+    # Crystalized methods can be redefined without restarting, if running in a live-reloading environment.
     # If they are redefined with a different function body, the new function body
     # will result in a new digest and the FFI function will be recompiled and reattached.
     def define_crystalized_methods!(lib)
@@ -34,12 +35,12 @@ module CrystalRuby
             lib.build!
             return send(func.method_name, *args)
           end
-          unless lib.attached?(func.owner)
+          unless func.attached?
             should_reenter = func.attach_ffi_lib_functions!
             return send(func.method_name, *args) if should_reenter
           end
-          # All crystalruby functions are executed on the reactor to ensure
-          # all Crystal interop is executed from the same thread. (Needed to make GC and Fiber scheduler happy)
+          # All crystalruby functions are executed on the reactor to ensure Crystal/Ruby interop code is executed
+          # from a single same thread. (Needed to make GC and Fiber scheduler happy)
           # Type mapping (if required) is applied on arguments and on return values.
           func.map_retval(
             Reactor.schedule_work!(
@@ -58,14 +59,11 @@ module CrystalRuby
     # This is where we attach the top-level FFI functions of the shared object
     # to our library (yield and init) needed for successful operation of the reactor.
     # We also initialize the shared object (needed to start the GC) and
-    # start the reactor unless we are in single-thread mode.
+    # start the reactor, unless we are in single-thread mode.
     def attach_ffi_lib_functions!
       should_reenter = unwrapped?
       lib_file = lib.lib_file
-      lib.attachments[owner] = true
-      lib.methods.each_value do |method|
-        method.attach_ffi_func!
-      end
+      lib.methods.each_value(&:attach_ffi_func!)
       lib.singleton_class.class_eval do
         extend FFI::Library
         ffi_lib lib_file
@@ -86,8 +84,8 @@ module CrystalRuby
       should_reenter
     end
 
-    # This is where we attach the crystalized FFI functions to their related
-    # Ruby modules and classes. If a wrapper block has been passed to the crystalize function,
+    # Attaches the crystalized FFI functions to their related Ruby modules and classes.
+    # If a wrapper block has been passed to the crystalize function,
     # then the we also wrap the crystalized function using a prepended Module.
     def attach_ffi_func!
       argtypes = ffi_types
@@ -114,7 +112,7 @@ module CrystalRuby
       owner.attach_function ffi_name, argtypes, rettype, blocking: true
       around_wrapper_block = block
       method_name = self.method_name
-
+      @attached = true
       return unless around_wrapper_block
 
       @around_wrapper ||= begin
@@ -136,6 +134,14 @@ module CrystalRuby
       block && !@around_wrapper
     end
 
+    def attached?
+      @attached
+    end
+
+    def unattach!
+      @attached = false
+    end
+
     def ffi_name
       lib_fn_name + (async && !config.single_thread_mode ? "_async" : "")
     end

data/lib/crystalruby/library.rb

@@ -8,7 +8,7 @@ module CrystalRuby
     CR_COMPILE_MUX = Mutex.new
     CR_ATTACH_MUX = Mutex.new
 
-    attr_accessor :name, :methods, :chunks, :root_dir, :lib_dir, :src_dir, :codegen_dir, :attachments, :reactor
+    attr_accessor :name, :methods, :chunks, :root_dir, :lib_dir, :src_dir, :codegen_dir, :reactor
 
     @libs_by_name = {}
 
@@ -30,13 +30,10 @@ module CrystalRuby
       self.name = name
       self.methods = {}
       self.chunks = []
-      self.attachments = Hash.new(false)
       initialize_library!
     end
 
-    # This method is used to
-    # bootstrap a library filesystem,
-    # and generate a top level index.cr and shard file if
+    # Bootstraps the library filesystem and generates top level index.cr and shard files if
     # these do not already exist.
     def initialize_library!
       @root_dir, @lib_dir, @src_dir, @codegen_dir = [
@@ -57,11 +54,11 @@ module CrystalRuby
       YAML
     end
 
-    # This is where we instantiate the crystalized method as a CrystalRuby::Function
-    # and trigger the generation of the crystal code.
+    # Generates and stores a reference to a new CrystalRuby::Function
+    # and triggers the generation of the crystal code. (See write_chunk)
     def crystalize_method(method, args, returns, function_body, async, &block)
       CR_ATTACH_MUX.synchronize do
-        attachments.delete(method.owner)
+        methods.each_value(&:unattach!)
         method_key = "#{method.owner.name}/#{method.name}"
         methods[method_key] = Function.new(
           method: method,
@@ -100,8 +97,7 @@ module CrystalRuby
     end
 
     def compiled?
-      index_contents = self.index_contents
-      File.exist?(lib_file) && chunks.all? do |chunk|
+      @compiled ||= File.exist?(lib_file) && chunks.all? do |chunk|
         chunk_data = chunk[:body]
         file_digest = Digest::MD5.hexdigest chunk_data
         fname = chunk[:chunk_name]
@@ -115,10 +111,6 @@ module CrystalRuby
       ""
     end
 
-    def attached?(owner)
-      attachments[owner]
-    end
-
     def register_type!(type)
       @types_cache ||= {}
       @types_cache[type.name] = type.type_defn
@@ -183,7 +175,8 @@ module CrystalRuby
         filename = (codegen_dir / module_name / "#{chunk_name}_#{file_digest}.cr").to_s
 
         unless existing.delete(filename)
-          @attached = false
+          methods.each_value(&:unattach!)
+          @compiled = false
           FileUtils.mkdir_p(codegen_dir / module_name)
           File.write(filename, body)
         end

data/lib/crystalruby/reactor.rb

@@ -1,10 +1,8 @@
 module CrystalRuby
-  # The Reactor represents a singleton Thread
-  # responsible for running all Ruby/crystal interop code.
-  # Crystal's Fiber scheduler and GC assumes all code is run on a single thread.
-  # This class is responsible for multiplexing Ruby and Crystal code on a single thread,
-  # to allow safe invocation of Crystal code from across any number of Ruby threads.
-  # Functions annotated with async: true, are executed using callbacks to allow these to be multi-plexed in a non-blocking manner.
+  # The Reactor represents a singleton Thread responsible for running all Ruby/crystal interop code.
+  # Crystal's Fiber scheduler and GC assume all code is run on a single thread.
+  # This class is responsible for multiplexing Ruby and Crystal code on a single thread.
+  # Functions annotated with async: true, are executed using callbacks to allow these to be interleaved without blocking.
 
   module Reactor
     module_function
@@ -45,7 +43,6 @@ module CrystalRuby
       error_type = error_type.to_sym
       is_exception_type = Object.const_defined?(error_type) && Object.const_get(error_type).ancestors.include?(Exception)
       error_type = is_exception_type ? Object.const_get(error_type) : RuntimeError
-      tid = tid.zero? ? Reactor.current_thread_id : tid
       raise error_type.new(message) unless THREAD_MAP.key?(tid)
 
       THREAD_MAP[tid][:error] = error_type.new(message)

data/lib/crystalruby/types/array.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CrystalRuby::Types
   Array = Type.new(
     :Array,
@@ -6,9 +8,8 @@ module CrystalRuby::Types
 
   def self.Array(type)
     Type.validate!(type)
-    Type.new("Array", inner_types: [type], accept_if: [::Array]
-    ) do |a|
-      a.map!{|v| type.interpret!(v) }
+    Type.new("Array", inner_types: [type], accept_if: [::Array]) do |a|
+      a.map! { |v| type.interpret!(v) }
     end
   end
 end

data/lib/crystalruby/types/hash.rb

@@ -1,15 +1,17 @@
+# frozen_string_literal: true
+
 module CrystalRuby::Types
   Hash = Type.new(
     :Hash,
-    error: "Hash type must have 2 type parameters. E.g. Hash(Float64, String)",
+    error: "Hash type must have 2 type parameters. E.g. Hash(Float64, String)"
   )
 
   def self.Hash(key_type, value_type)
     Type.validate!(key_type)
     Type.validate!(value_type)
     Type.new("Hash", inner_types: [key_type, value_type], accept_if: [::Hash]) do |h|
-      h.transform_keys!{|k| key_type.interpret!(k) }
-      h.transform_values!{|v| value_type.interpret!(v) }
+      h.transform_keys! { |k| key_type.interpret!(k) }
+      h.transform_values! { |v| value_type.interpret!(v) }
     end
   end
 end

data/lib/crystalruby/types/named_tuple.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CrystalRuby::Types
   NamedTuple = Type.new(
     :NamedTuple,
@@ -6,7 +8,7 @@ module CrystalRuby::Types
 
   def self.NamedTuple(types_hash)
     types_hash.keys.each do |key|
-      raise "NamedTuple keys must be symbols" unless key.kind_of?(::Symbol) || key.respond_to?(:to_sym)
+      raise "NamedTuple keys must be symbols" unless key.is_a?(::Symbol) || key.respond_to?(:to_sym)
     end
     types_hash.values.each do |value_type|
       Type.validate!(value_type)
@@ -14,9 +16,10 @@ module CrystalRuby::Types
     keys = types_hash.keys.map(&:to_sym)
     values = types_hash.values
     Type.new("NamedTuple", inner_types: values, inner_keys: keys, accept_if: [::Hash]) do |h|
-      h.transform_keys!{|k| k.to_sym }
+      h.transform_keys! { |k| k.to_sym }
       raise "Invalid keys for named tuple" unless h.keys.length == keys.length
-      raise "Invalid keys for named tuple" unless h.keys.all?{|k| keys.include?(k)}
+      raise "Invalid keys for named tuple" unless h.keys.all? { |k| keys.include?(k) }
+
       h.each do |key, value|
         h[key] = values[keys.index(key)].interpret!(value)
       end

data/lib/crystalruby/types/time.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module CrystalRuby::Types
-  require 'date'
+  require "date"
   Time = Type.new(:Time, accept_if: [::Time, ::String]) do |v|
     DateTime.parse(v)
   end

data/lib/crystalruby/types/tuple.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CrystalRuby::Types
   Tuple = Type.new(
     :Tuple,
@@ -9,7 +11,7 @@ module CrystalRuby::Types
       Type.validate!(value_type)
     end
     Type.new("Tuple", inner_types: types, accept_if: [::Array]) do |a|
-      a.map!.with_index{|v, i| self.inner_types[i].interpret!(v) }
+      a.map!.with_index { |v, i| inner_types[i].interpret!(v) }
     end
   end
 end

data/lib/crystalruby/types/typedef.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "type_serializer"
 
 module CrystalRuby
@@ -5,7 +7,7 @@ module CrystalRuby
     class Typedef; end
 
     def self.Typedef(type)
-      return type if type.kind_of?(Class) && type < Typedef
+      return type if type.is_a?(Class) && type < Typedef
 
       Class.new(Typedef) do
         define_singleton_method(:union_types) do

data/lib/crystalruby/types/union_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CrystalRuby
   module Types
     class UnionType < Type
@@ -26,12 +28,12 @@ module CrystalRuby
 
       def interpret!(raw)
         union_types.each do |type|
-          if type.interprets?(raw)
-            begin
-              return type.interpret!(raw)
-            rescue
-              # Pass
-            end
+          next unless type.interprets?(raw)
+
+          begin
+            return type.interpret!(raw)
+          rescue StandardError
+            # Pass
           end
         end
         raise "Invalid deserialized value #{raw} for type #{inspect}"

data/lib/crystalruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Crystalruby
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: crystalruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Wouter Coppieters
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-24 00:00:00.000000000 Z
+date: 2024-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: digest