Add Thread::Local(T) (#15616)

The `@[ThreadLocal]` annotation only works on some targets and doesn't allow registering a destructor callback that will be invoked when a thread shuts down.

We currently don't have threads shutting down, but with [RFC 2] it will start happening (at least isolated contexts are expected to shut down, others should eventually evolve to shut down too), or use the complex `Crystal::ThreadLocalValue` to tie a value to a thread, which in turn requires finalize methods

[RFC 2]: crystal-lang/rfcs#2

Author: ysbaddaden

src/crystal/system/thread_local.cr

@@ -0,0 +1,41 @@
+class Thread
+  struct Local(T)
+    # Reserves space for saving a `T` reference on each thread.
+    def initialize
+      {% unless T < Reference || T < Pointer || T.union_types.all? { |t| t == Nil || t < Reference } %}
+        {% raise "Can only create Thread::Local with reference types, nilable reference types, or pointer types, not {{T}}" %}
+      {% end %}
+    end
+
+    # Reserves space for saving a `T` reference on each thread and registers a
+    # destructor that will be called when a thread terminates if the local value
+    # has been set.
+    def initialize(&destructor : Proc(T, Nil))
+      {% unless T < Reference || T < Pointer || T.union_types.all? { |t| t == Nil || t < Reference } %}
+        {% raise "Can only create Thread::Local with reference types, nilable reference types, or pointer types, not {{T}}" %}
+      {% end %}
+    end
+
+    # Returns the current local value for the thread; if unset constructs one by
+    # yielding and sets it as the current local value.
+    def get(& : -> T) : T
+      get? || set(yield)
+    end
+
+    # Returns the current local value for the thread or `nil` if there is none.
+    # def get? : T?
+
+    # Sets *value* as the current local value for the thread.
+    # def set(value : T) : T
+  end
+end
+
+{% if flag?(:wasi) %}
+  require "./wasi/thread_local"
+{% elsif flag?(:unix) %}
+  require "./unix/thread_local"
+{% elsif flag?(:win32) %}
+  require "./win32/thread_local"
+{% else %}
+  {% raise "Thread not supported" %}
+{% end %}

src/crystal/system/unix/thread_local.cr

@@ -0,0 +1,34 @@
+require "c/pthread"
+
+class Thread
+  struct Local(T)
+    @key = uninitialized LibC::PthreadKeyT
+
+    def initialize
+      previous_def
+      @key = pthread_key_create(nil)
+    end
+
+    def initialize(&destructor : Proc(T, Nil))
+      previous_def(&destructor)
+      @key = pthread_key_create(destructor.unsafe_as(Proc(Void*, Nil)))
+    end
+
+    private def pthread_key_create(destructor)
+      err = LibC.pthread_key_create(out key, destructor)
+      raise RuntimeError.from_os_error("pthread_key_create", Errno.new(err)) unless err == 0
+      key
+    end
+
+    def get? : T?
+      pointer = LibC.pthread_getspecific(@key)
+      pointer.as(T) unless pointer.null?
+    end
+
+    def set(value : T) : T
+      err = LibC.pthread_setspecific(@key, value.as(Void*))
+      raise RuntimeError.from_os_error("pthread_setspecific", Errno.new(err)) unless err == 0
+      value
+    end
+  end
+end

src/crystal/system/wasi/thread_local.cr

@@ -0,0 +1,21 @@
+class Thread
+  struct Local(T)
+    @value : T?
+
+    def initialize
+      previous_def
+    end
+
+    def initialize(&destructor : T ->)
+      previous_def(&destructor)
+    end
+
+    def get? : T?
+      @value
+    end
+
+    def set(value : T) : T
+      @value = value
+    end
+  end
+end

src/crystal/system/win32/thread_local.cr

@@ -0,0 +1,34 @@
+require "c/fibersapi"
+
+class Thread
+  struct Local(T)
+    @key = uninitialized LibC::DWORD
+
+    def initialize
+      previous_def
+      @key = fls_alloc(nil)
+    end
+
+    def initialize(&destructor : Proc(T, Nil))
+      previous_def(&destructor)
+      @key = fls_alloc(destructor.unsafe_as(LibC::FLS_CALLBACK_FUNCTION))
+    end
+
+    private def fls_alloc(destructor)
+      key = LibC.FlsAlloc(destructor)
+      raise RuntimeError.from_winerror("FlsAlloc: out of indexes") if key == LibC::FLS_OUT_OF_INDEXES
+      key
+    end
+
+    def get? : T?
+      pointer = LibC.FlsGetValue(@key)
+      pointer.as(T) unless pointer.null?
+    end
+
+    def set(value : T) : T
+      ret = LibC.FlsSetValue(@key, value.as(T))
+      raise RuntimeError.from_winerror("FlsSetValue") if ret == 0
+      value
+    end
+  end
+end

src/lib_c/aarch64-android/c/pthread.cr

@@ -26,6 +26,7 @@ lib LibC
   fun pthread_getspecific(__key : PthreadKeyT) : Void*
   fun pthread_join(__pthread : PthreadT, __return_value_ptr : Void**) : Int
   fun pthread_key_create(__key_ptr : PthreadKeyT*, __key_destructor : Void* ->) : Int
+  fun pthread_key_delete(__key_ptr : PthreadKeyT) : Int
 
   fun pthread_mutexattr_destroy(__attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(__attr : PthreadMutexattrT*) : Int

src/lib_c/aarch64-darwin/c/pthread.cr

@@ -13,9 +13,12 @@ lib LibC
   fun pthread_cond_wait(x0 : PthreadCondT*, x1 : PthreadMutexT*) : Int
   fun pthread_create(x0 : PthreadT*, x1 : PthreadAttrT*, x2 : Void* -> Void*, x3 : Void*) : Int
   fun pthread_detach(x0 : PthreadT) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_get_stackaddr_np(x0 : PthreadT) : Void*
   fun pthread_get_stacksize_np(x0 : PthreadT) : SizeT
   fun pthread_join(x0 : PthreadT, x1 : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(x0 : PthreadMutexattrT*, x1 : Int) : Int
@@ -26,4 +29,5 @@ lib LibC
   fun pthread_mutex_unlock(x0 : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/aarch64-darwin/c/sys/types.cr

@@ -40,6 +40,7 @@ lib LibC
   end
 
   type PthreadT = Void*
+  alias PthreadKeyT = UInt
   alias SSizeT = Long
   alias SusecondsT = Int
   alias TimeT = Long

src/lib_c/aarch64-linux-gnu/c/pthread.cr

@@ -25,8 +25,11 @@ lib LibC
   fun pthread_create(newthread : PthreadT*, attr : PthreadAttrT*, start_routine : Void* -> Void*, arg : Void*) : Int
   fun pthread_detach(th : PthreadT) : Int
   fun pthread_getattr_np(thread : PthreadT, attr : PthreadAttrT*) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_equal(thread1 : PthreadT, thread2 : PthreadT) : Int
   fun pthread_join(th : PthreadT, thread_return : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(attr : PthreadMutexattrT*, type : Int) : Int
@@ -37,4 +40,5 @@ lib LibC
   fun pthread_mutex_unlock(mutex : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(PthreadT, Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/aarch64-linux-gnu/c/sys/types.cr

@@ -41,6 +41,7 @@ lib LibC
   end
 
   alias PthreadT = ULong
+  alias PthreadKeyT = UInt
   alias SSizeT = Long
   alias SusecondsT = Long
   alias TimeT = Long

src/lib_c/aarch64-linux-musl/c/pthread.cr

@@ -17,7 +17,10 @@ lib LibC
   fun pthread_create(x0 : PthreadT*, x1 : PthreadAttrT*, x2 : Void* -> Void*, x3 : Void*) : Int
   fun pthread_detach(x0 : PthreadT) : Int
   fun pthread_getattr_np(x0 : PthreadT, x1 : PthreadAttrT*) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_join(x0 : PthreadT, x1 : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(x0 : PthreadMutexattrT*, x1 : Int) : Int
@@ -28,4 +31,5 @@ lib LibC
   fun pthread_mutex_unlock(x0 : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(PthreadT, Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/aarch64-linux-musl/c/sys/types.cr

@@ -54,6 +54,7 @@ lib LibC
   end
 
   type PthreadT = Void*
+  alias PthreadKeyT = UInt
   alias SSizeT = Long
   alias SusecondsT = Long
   alias TimeT = Long

src/lib_c/arm-linux-gnueabihf/c/pthread.cr

@@ -25,8 +25,11 @@ lib LibC
   fun pthread_create(newthread : PthreadT*, attr : PthreadAttrT*, start_routine : Void* -> Void*, arg : Void*) : Int
   fun pthread_detach(th : PthreadT) : Int
   fun pthread_getattr_np(thread : PthreadT, attr : PthreadAttrT*) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_equal(thread1 : PthreadT, thread2 : PthreadT) : Int
   fun pthread_join(th : PthreadT, thread_return : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(attr : PthreadMutexattrT*, type : Int) : Int
@@ -37,4 +40,5 @@ lib LibC
   fun pthread_mutex_unlock(mutex : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(PthreadT, Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/arm-linux-gnueabihf/c/sys/types.cr

@@ -54,6 +54,7 @@ lib LibC
   end
 
   alias PthreadT = ULong
+  alias PthreadKeyT = UInt
   alias SSizeT = Int
   alias SusecondsT = Long
   alias TimeT = Long

src/lib_c/i386-linux-gnu/c/pthread.cr

@@ -25,7 +25,10 @@ lib LibC
   fun pthread_create(newthread : PthreadT*, attr : PthreadAttrT*, start_routine : Void* -> Void*, arg : Void*) : Int
   fun pthread_detach(th : PthreadT) : Int
   fun pthread_getattr_np(thread : PthreadT, attr : PthreadAttrT*) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_join(th : PthreadT, thread_return : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(attr : PthreadMutexattrT*, type : Int) : Int
@@ -36,4 +39,5 @@ lib LibC
   fun pthread_mutex_unlock(mutex : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(PthreadT, Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/i386-linux-gnu/c/sys/types.cr

@@ -41,6 +41,7 @@ lib LibC
   end
 
   alias PthreadT = ULong
+  alias PthreadKeyT = UInt
   alias SSizeT = Int
   alias SusecondsT = Long
   alias TimeT = Long

src/lib_c/i386-linux-musl/c/pthread.cr

@@ -17,7 +17,10 @@ lib LibC
   fun pthread_create(x0 : PthreadT*, x1 : PthreadAttrT*, x2 : Void* -> Void*, x3 : Void*) : Int
   fun pthread_detach(x0 : PthreadT) : Int
   fun pthread_getattr_np(x0 : PthreadT, x1 : PthreadAttrT*) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_join(x0 : PthreadT, x1 : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(x0 : PthreadMutexattrT*, x1 : Int) : Int
@@ -28,4 +31,5 @@ lib LibC
   fun pthread_mutex_unlock(x0 : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(PthreadT, Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/i386-linux-musl/c/sys/types.cr

@@ -54,6 +54,7 @@ lib LibC
   end
 
   type PthreadT = Void*
+  alias PthreadKeyT = UInt
   alias SSizeT = Int
   alias SusecondsT = Long
   alias TimeT = Long

src/lib_c/x86_64-darwin/c/pthread.cr

@@ -15,7 +15,10 @@ lib LibC
   fun pthread_detach(x0 : PthreadT) : Int
   fun pthread_get_stackaddr_np(x0 : PthreadT) : Void*
   fun pthread_get_stacksize_np(x0 : PthreadT) : SizeT
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_join(x0 : PthreadT, x1 : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(x0 : PthreadMutexattrT*, x1 : Int) : Int
@@ -26,4 +29,5 @@ lib LibC
   fun pthread_mutex_unlock(x0 : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/x86_64-darwin/c/sys/types.cr

@@ -40,6 +40,7 @@ lib LibC
   end
 
   type PthreadT = Void*
+  alias PthreadKeyT = UInt
   alias SSizeT = Long
   alias SusecondsT = Int
   alias TimeT = Long

src/lib_c/x86_64-dragonfly/c/pthread.cr

@@ -19,7 +19,10 @@ lib LibC
   fun pthread_cond_wait(x0 : PthreadCondT*, x1 : PthreadMutexT*) : Int
   fun pthread_create(x0 : PthreadT*, x1 : PthreadAttrT*, x2 : Void* -> Void*, x3 : Void*) : Int
   fun pthread_detach(x0 : PthreadT) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_join(x0 : PthreadT, x1 : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(x0 : PthreadMutexattrT*, x1 : Int) : Int
@@ -30,4 +33,5 @@ lib LibC
   fun pthread_mutex_unlock(x0 : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(PthreadT, Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/x86_64-dragonfly/c/sys/types.cr

@@ -17,6 +17,7 @@ lib LibC
   type PthreadAttrT = Void*
   type PthreadCondT = Void*
   type PthreadCondattrT = Void*
+  alias PthreadKeyT = Int
   type PthreadMutexT = Void*
   type PthreadMutexattrT = Void*
   type PthreadT = Void*

src/lib_c/x86_64-freebsd/c/pthread.cr

@@ -19,7 +19,10 @@ lib LibC
   fun pthread_cond_wait(x0 : PthreadCondT*, x1 : PthreadMutexT*) : Int
   fun pthread_create(x0 : PthreadT*, x1 : PthreadAttrT*, x2 : Void* -> Void*, x3 : Void*) : Int
   fun pthread_detach(x0 : PthreadT) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_join(x0 : PthreadT, x1 : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(x0 : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(x0 : PthreadMutexattrT*, x1 : Int) : Int
@@ -30,4 +33,5 @@ lib LibC
   fun pthread_mutex_unlock(x0 : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_set_name_np(PthreadT, Char*)
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/x86_64-freebsd/c/sys/types.cr

@@ -17,6 +17,7 @@ lib LibC
   type PthreadAttrT = Void*
   type PthreadCondT = Void*
   type PthreadCondattrT = Void*
+  alias PthreadKeyT = Int
   type PthreadMutexT = Void*
   type PthreadMutexattrT = Void*
   type PthreadT = Void*

src/lib_c/x86_64-linux-gnu/c/pthread.cr

@@ -25,7 +25,10 @@ lib LibC
   fun pthread_create(newthread : PthreadT*, attr : PthreadAttrT*, start_routine : Void* -> Void*, arg : Void*) : Int
   fun pthread_detach(th : PthreadT) : Int
   fun pthread_getattr_np(thread : PthreadT, attr : PthreadAttrT*) : Int
+  fun pthread_getspecific(PthreadKeyT) : Void*
   fun pthread_join(th : PthreadT, thread_return : Void**) : Int
+  fun pthread_key_create(PthreadKeyT*, (Void*) ->) : Int
+  fun pthread_key_delete(PthreadKeyT) : Int
   fun pthread_mutexattr_destroy(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_init(attr : PthreadMutexattrT*) : Int
   fun pthread_mutexattr_settype(attr : PthreadMutexattrT*, type : Int) : Int
@@ -36,4 +39,5 @@ lib LibC
   fun pthread_mutex_unlock(mutex : PthreadMutexT*) : Int
   fun pthread_self : PthreadT
   fun pthread_setname_np(PthreadT, Char*) : Int
+  fun pthread_setspecific(PthreadKeyT, Void*) : Int
 end

src/lib_c/x86_64-linux-gnu/c/sys/types.cr

@@ -40,6 +40,7 @@ lib LibC
     __align : Int
   end
 
+  alias PthreadKeyT = UInt
   alias PthreadT = ULong
   alias SSizeT = Long
   alias SusecondsT = Long