thread_safety 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da80797122c8f15667ea491b39d080c31230d1afd179f14c190ed046471635b6
-  data.tar.gz: d3c8f576439d8956eb082105ef45659dcf3b1bb3284a122b7721f8f953222030
+  metadata.gz: 2a97ea1ef817cda7d227855e1922f4af2eff2162f8494ea68fc2743f0febf2d0
+  data.tar.gz: bb7b718805c670511e7009c0c08c53fad6f997913db6473ea6339606eefbe576
 SHA512:
-  metadata.gz: 8946716cb9f51a90ae2e6b435ef89878867da71fa2fc202652669f8c0dcfc245231b9224e3f3d7a58afe51969bf79c3c77c375b875ee428818f601c4db0dceb4
-  data.tar.gz: 2434d000df9d525bd3eabe0f8fcb7a455634e04719afcabc0190cec48291274952820d5e2a191d1b6c4059919e938f93c5859f281a4ec7a9d3b0fbff26be6a2d
+  metadata.gz: 3f05f018aaf6ece0dcc642b376fc9b91deba62b53575c1a096073e8b72d9dc73aa51d6f1d9ab808b48f1ff5b78ee51313d9fdaf9e557595767f668d43acfe775
+  data.tar.gz: a1103a44b093da5e15b85bbe6399fa23c46728d86b8907f12688337f06d74da1df35a167e11baf774f87b7d81ac56d9b7643feb447375e86f8b61ce89cd946de

data/.rubocop.yml

@@ -1,8 +1,9 @@
-AllCops:
-  TargetRubyVersion: 3.1
+inherit_gem:
+  rubocop-shopify: rubocop.yml
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
+AllCops:
+  SuggestExtensions: false
 
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
+Style/GlobalVars:
+  Exclude:
+    - ext/extconf_base.rb

data/README.md

@@ -1,13 +1,13 @@
 # Thread Safety
 
-This gem plugs into [Ruby's Modular GC](https://github.com/ruby/ruby/blob/master/gc/README.md) feature to detect potential thread-safety issues through reporting cross-thread writes.
+This gem plugs into [Ruby's Modular GC](https://github.com/ruby/ruby/blob/master/gc/README.md) feature to detect potential thread-safety issues through reporting cross-thread and cross-fiber writes.
 
 ## Usage
 
 To use the Thread Safety gem, follow these steps:
 
 1. Build Ruby with Modular GC enabled by [following the "Building Ruby with Modular GC" guide](https://github.com/ruby/ruby/blob/master/gc/README.md#building-ruby-with-modular-gc).
-  - Since Modular GC is still an experimental feature, this gem does not yet support released versions of Ruby. You must use the development version of Ruby.
+    - Since Modular GC is still an experimental feature, this gem does not yet support released versions of Ruby. You must use the development version of Ruby.
 2. Install the gem.
 3. Implement a callback to report when a thread-safety issue is detected:
 
@@ -16,3 +16,70 @@ To use the Thread Safety gem, follow these steps:
       puts "Offense: #{offense.object} #{offense.backtrace[0].path}:#{offense.backtrace[0].lineno}"
     end
     ```
+4. Run your code with `thread_safety` in the command line.
+
+    For example, if you had the following script in `test.rb` with the `callback` from above:
+
+    ```ruby
+    obj = []
+    Thread.new do
+      obj << 1
+    end.join
+    ```
+
+    Then you could run it as such:
+
+    ```sh
+    $ thread_safety ruby test.rb
+    Offense: [] test.rb:9
+    ```
+
+## API
+
+### `ThreadSafety.callback = cb`
+
+Sets the callback that is called when an offense is detected. `cb` must accept one argument `offense`, which is of type [`ThreadSafety::Offense`](#threadsafetyoffense).
+
+Set `cb` to nil to turn Thread Safety off.
+
+### `ThreadSafety.enabled = enabled`
+
+Sets Thread Safety to be enabled or disabled globally. Defaults to `false`.
+
+### `ThreadSafety.suppress_warnings {}`
+
+Disables Thread Safety offense detection for the block. This is useful for silencing offenses that are false-positives.
+
+For example:
+
+```ruby
+obj = []
+Thread.new do
+  obj << 1
+  ThreadSafety.suppress_warnings { obj << 2 }
+  obj << 3
+end.join
+```
+
+Outputs:
+
+```
+$ thread_safety ruby script.rb
+Offense: [] script.rb:9
+Offense: [1, 2] script.rb:11
+```
+
+### `Thread#thread_safety_enabled = enabled` and `Fiber#thread_safety_enabled = enabled`
+
+Sets Thread Safety to be enabled or disabled for a particular Thread or Fiber. This value will ignore the global value set by `ThreadSafety.enabled=`, so you can use this to implement allowlists or denylists.
+
+### `ThreadSafety::Offense`
+
+Class for a warning. Contains the following fields:
+
+- `object`: The object that is being written to.
+- `backtrace`: An array containing the Ruby backtrace of the write.
+- `created_fiber`: The Fiber object that created `object`.
+- `created_thread`: The Thread object that created `object`.
+- `access_thread`: The Thread object that wrote into `object`.
+- `access_fiber`: The Fiber object that wrote into `object`.

data/Rakefile

@@ -1,9 +1,21 @@
 # frozen_string_literal: true
 
-# require "bundler/gem_tasks"
+require "bundler/gem_tasks"
 require "minitest/test_task"
 
-Minitest::TestTask.create
+class ThreadSafetyTestTask < Minitest::TestTask
+  def ruby(*args, **options, &block)
+    env = { "RUBY_GC_LIBRARY" => "thread_safety" }
+
+    if args.length > 1
+      sh(env, RUBY, *args, **options, &block)
+    else
+      sh(env, "#{RUBY} #{args.first}", **options, &block)
+    end
+  end
+end
+
+ThreadSafetyTestTask.create
 
 # require "rubocop/rake_task"
 
@@ -21,7 +33,7 @@ end)
 
 task :check_modular_gc do
   modular_gc_dir = RbConfig::CONFIG["modular_gc_dir"]
-  fail "Not using Ruby with modular GC enabled" if !modular_gc_dir || modular_gc_dir.empty?
+  raise "Not using Ruby with modular GC enabled" if !modular_gc_dir || modular_gc_dir.empty?
 end
 
 Rake::ExtensionTask.new do |ext|

data/exe/thread_safety

@@ -13,5 +13,6 @@ modular_gc_dir = RbConfig::CONFIG["modular_gc_dir"]
 raise "Not using Ruby with modular GC enabled" if !modular_gc_dir || modular_gc_dir.empty?
 
 ENV["RUBY_GC_LIBRARY"] = "thread_safety"
+ENV["THREAD_SAFETY_ENABLE"] = "true"
 
 exec(*ARGV)

data/ext/extconf.rb

@@ -2,14 +2,29 @@
 
 require_relative "extconf_base"
 
+ruby_version = "#{RbConfig::CONFIG["MAJOR"]}.#{RbConfig::CONFIG["MINOR"]}"
+
+gc_path = File.expand_path("gc-#{ruby_version}", __dir__)
+$INCFLAGS.prepend("-I#{gc_path} ") # rubocop:disable Style/GlobalVars
+
+# Apply patches to vendored GC files
+patches_dir = File.join(gc_path, "patches")
+if File.directory?(patches_dir)
+  Dir.glob(File.join(patches_dir, "*.patch")).sort.each do |patch_file|
+    Dir.chdir(gc_path) do
+      system("patch", "-p1", "-N", "--silent", "-i", patch_file) || true
+    end
+  end
+end
+
 create_gc_makefile("thread_safety") do |makefile|
   [
     *makefile,
 
     <<~MAKEFILE,
-    install: install-modular-gc-dir
-    install-modular-gc-dir: install-so
-    	cp $(DLLIB) $(modular_gc_dir)
+      install: install-modular-gc-dir
+      install-modular-gc-dir: install-so
+      	cp $(DLLIB) $(modular_gc_dir)
     MAKEFILE
   ]
 end

data/ext/gc-3.4/darray.h

@@ -0,0 +1,220 @@
+/*
+ * Vendored from Ruby v3_4_8: darray.h
+ *
+ * This file is vendored because the modular GC for Ruby 3.4 needs a darray.h
+ * that matches the Ruby 3.4 API. The ext/darray.h is from Ruby 4.0 and has
+ * different function names (_without_gc variants).
+ *
+ * This vendoring can be removed when Ruby 3.4 support is dropped and the
+ * minimum Ruby version is 4.0+.
+ *
+ * License: Ruby License (same as Ruby itself)
+ */
+
+#ifndef RUBY_DARRAY_H
+#define RUBY_DARRAY_H
+
+#include <stdint.h>
+#include <stddef.h>
+#include <stdlib.h>
+
+// Type for a dynamic array. Use to declare a dynamic array.
+// It is a pointer so it fits in st_table nicely. Designed
+// to be fairly type-safe.
+//
+// NULL is a valid empty dynamic array.
+//
+// Example:
+//      rb_darray(char) char_array = NULL;
+//      rb_darray_append(&char_array, 'e');
+//      printf("pushed %c\n", *rb_darray_ref(char_array, 0));
+//      rb_darray_free(char_array);
+//
+#define rb_darray(T) struct { rb_darray_meta_t meta; T data[]; } *
+
+// Copy an element out of the array. Warning: not bounds checked.
+//
+// T rb_darray_get(rb_darray(T) ary, size_t idx);
+//
+#define rb_darray_get(ary, idx) ((ary)->data[(idx)])
+
+// Assign to an element. Warning: not bounds checked.
+//
+// void rb_darray_set(rb_darray(T) ary, size_t idx, T element);
+//
+#define rb_darray_set(ary, idx, element) ((ary)->data[(idx)] = (element))
+
+// Get a pointer to an element. Warning: not bounds checked.
+//
+// T *rb_darray_ref(rb_darray(T) ary, size_t idx);
+//
+#define rb_darray_ref(ary, idx) (&((ary)->data[(idx)]))
+
+/* Copy a new element into the array. ptr_to_ary is evaluated multiple times.
+ *
+ * void rb_darray_append(rb_darray(T) *ptr_to_ary, T element);
+ */
+#define rb_darray_append(ptr_to_ary, element) do {  \
+    rb_darray_ensure_space((ptr_to_ary), \
+                           sizeof(**(ptr_to_ary)), \
+                           sizeof((*(ptr_to_ary))->data[0])); \
+    rb_darray_set(*(ptr_to_ary), \
+                  (*(ptr_to_ary))->meta.size, \
+                  (element)); \
+    (*(ptr_to_ary))->meta.size++; \
+} while (0)
+
+#define rb_darray_insert(ptr_to_ary, idx, element) do { \
+    rb_darray_ensure_space((ptr_to_ary), \
+                           sizeof(**(ptr_to_ary)), \
+                           sizeof((*(ptr_to_ary))->data[0])); \
+    MEMMOVE( \
+        rb_darray_ref(*(ptr_to_ary), idx + 1), \
+        rb_darray_ref(*(ptr_to_ary), idx), \
+        (*(ptr_to_ary))->data[0], \
+        rb_darray_size(*(ptr_to_ary)) - idx); \
+    rb_darray_set(*(ptr_to_ary), idx, element); \
+    (*(ptr_to_ary))->meta.size++; \
+} while (0)
+
+// Iterate over items of the array in a for loop
+//
+#define rb_darray_foreach(ary, idx_name, elem_ptr_var) \
+    for (size_t idx_name = 0; idx_name < rb_darray_size(ary) && ((elem_ptr_var) = rb_darray_ref(ary, idx_name)); ++idx_name)
+
+// Iterate over valid indices in the array in a for loop
+//
+#define rb_darray_for(ary, idx_name) \
+    for (size_t idx_name = 0; idx_name < rb_darray_size(ary); ++idx_name)
+
+/* Make a dynamic array of a certain size. All bytes backing the elements are set to zero.
+ * Return 1 on success and 0 on failure.
+ *
+ * Note that NULL is a valid empty dynamic array.
+ *
+ * void rb_darray_make(rb_darray(T) *ptr_to_ary, size_t size);
+ */
+#define rb_darray_make(ptr_to_ary, size) \
+    rb_darray_make_impl((ptr_to_ary), size, sizeof(**(ptr_to_ary)), sizeof((*(ptr_to_ary))->data[0]))
+
+/* Resize the darray to a new capacity. The new capacity must be greater than
+ * or equal to the size of the darray.
+ *
+ * void rb_darray_resize_capa(rb_darray(T) *ptr_to_ary, size_t capa);
+ */
+#define rb_darray_resize_capa(ptr_to_ary, capa) \
+    rb_darray_resize_capa_impl((ptr_to_ary), capa, sizeof(**(ptr_to_ary)), sizeof((*(ptr_to_ary))->data[0]))
+
+#define rb_darray_data_ptr(ary) ((ary)->data)
+
+typedef struct rb_darray_meta {
+    size_t size;
+    size_t capa;
+} rb_darray_meta_t;
+
+/* Set the size of the array to zero without freeing the backing memory.
+ * Allows reusing the same array. */
+static inline void
+rb_darray_clear(void *ary)
+{
+    rb_darray_meta_t *meta = ary;
+    if (meta) {
+        meta->size = 0;
+    }
+}
+
+// Get the size of the dynamic array.
+//
+static inline size_t
+rb_darray_size(const void *ary)
+{
+    const rb_darray_meta_t *meta = ary;
+    return meta ? meta->size : 0;
+}
+
+
+static inline void
+rb_darray_pop(void *ary, size_t count)
+{
+    rb_darray_meta_t *meta = ary;
+    meta->size -= count;
+}
+
+// Get the capacity of the dynamic array.
+//
+static inline size_t
+rb_darray_capa(const void *ary)
+{
+    const rb_darray_meta_t *meta = ary;
+    return meta ? meta->capa : 0;
+}
+
+/* Free the dynamic array. */
+static inline void
+rb_darray_free(void *ary)
+{
+    xfree(ary);
+}
+
+/* Internal function. Resizes the capacity of a darray. The new capacity must
+ * be greater than or equal to the size of the darray. */
+static inline void
+rb_darray_resize_capa_impl(void *ptr_to_ary, size_t new_capa, size_t header_size, size_t element_size)
+{
+    rb_darray_meta_t **ptr_to_ptr_to_meta = ptr_to_ary;
+    rb_darray_meta_t *meta = *ptr_to_ptr_to_meta;
+
+    rb_darray_meta_t *new_ary = xrealloc(meta, new_capa * element_size + header_size);
+
+    if (meta == NULL) {
+        /* First allocation. Initialize size. On subsequence allocations
+         * realloc takes care of carrying over the size. */
+        new_ary->size = 0;
+    }
+
+    RUBY_ASSERT(new_ary->size <= new_capa);
+
+    new_ary->capa = new_capa;
+
+    // We don't have access to the type of the dynamic array in function context.
+    // Write out result with memcpy to avoid strict aliasing issue.
+    memcpy(ptr_to_ary, &new_ary, sizeof(new_ary));
+}
+
+// Internal function
+// Ensure there is space for one more element.
+// Note: header_size can be bigger than sizeof(rb_darray_meta_t) when T is __int128_t, for example.
+static inline void
+rb_darray_ensure_space(void *ptr_to_ary, size_t header_size, size_t element_size)
+{
+    rb_darray_meta_t **ptr_to_ptr_to_meta = ptr_to_ary;
+    rb_darray_meta_t *meta = *ptr_to_ptr_to_meta;
+    size_t current_capa = rb_darray_capa(meta);
+    if (rb_darray_size(meta) < current_capa) return;
+
+    // Double the capacity
+    size_t new_capa = current_capa == 0 ? 1 : current_capa * 2;
+
+    rb_darray_resize_capa_impl(ptr_to_ary, new_capa, header_size, element_size);
+}
+
+static inline void
+rb_darray_make_impl(void *ptr_to_ary, size_t array_size, size_t header_size, size_t element_size)
+{
+    rb_darray_meta_t **ptr_to_ptr_to_meta = ptr_to_ary;
+    if (array_size == 0) {
+        *ptr_to_ptr_to_meta = NULL;
+        return;
+    }
+
+    rb_darray_meta_t *meta = xcalloc(array_size * element_size + header_size, 1);
+
+    meta->size = array_size;
+    meta->capa = array_size;
+
+    // We don't have access to the type of the dynamic array in function context.
+    // Write out result with memcpy to avoid strict aliasing issue.
+    memcpy(ptr_to_ary, &meta, sizeof(meta));
+}
+
+#endif /* RUBY_DARRAY_H */