RubyGateway 5.5.0 docs
(100% documented)
Open on GitHub Open in Dash

RbThread

Swift
public enum RbThread

This type provides a namespace for working with Ruby threads.

You cannot call Ruby on arbitrary threads: only the very first thread where RubyGateway gets used or threads created by Ruby’s Thread class.

There is no way to ‘attach’ the Ruby runtime to a thread created by client code (eg. one accessed via libdispatch).

Even when multiple Ruby threads are active, the VM executes just one at a time under control of a single lock known as the GVL. The GVL is given up over Ruby blocking operations and can be manually relinquished using RbThread.callWithoutGvl(callback:).

Inside a block that has given up the GVL, you must not call any Ruby code or it will at best crash. You can execute some code inside your GVL-free scope that is allowed to call Ruby using RbThread.callWithGvl(callback:).

Topics

Create a Ruby thread.

This is a simple wrapper around creating a Ruby Thread object.

note

You must retain the returned RbObject until the Ruby thread has finished to ensure the Swift callback is not released prematurely.

Declaration
Swift
public static func create(callback: @escaping () -> Void) -> RbObject?
Parameters
callback

Callback to make on the new thread
Return Value

The Ruby Thread object, or nil if there was a problem. See RbError.history for details of any error.

Does the Ruby VM know about the current thread?

Declaration
Swift
public static func isRubyThread() -> Bool
Return Value

true if this is the main thread or another created by Ruby where it’s OK to call Ruby functions.

From a Ruby thread, run some non-Ruby code without the GVL.

This allows other Ruby threads to run. See the Ruby source code for lengthy comments about how to do this safely.

Using this API ends up with no unblocking function for the section. See callWithoutGvl(unblocking:callback:) to configure that.

Declaration
Swift
public static func callWithoutGvl(callback: () -> Void)

A way to unblock a thread executing inside a callWithoutGvl section.

Declaration
Swift
public enum UnblockingFunc

From a Ruby thread, run some non-Ruby code without the GVL.

This allows other Ruby threads to run. See the Ruby source code for lengthy comments about how to do this safely.

This version of the API takes an unblocking function to be used when Ruby wants to interrupt the thread and get it back under GVL control.

Declaration
Swift
public static func callWithoutGvl(
    unblocking: UnblockingFunc, callback: () -> Void)

From a GVL-free section of code on a Ruby thread, reacquire the GVL and run some code.

This cannot be used to attach a native thread to Ruby. It should only be used from within the callback passed to callWithoutGvl(callback:). See the Ruby source code for more commentary.

Declaration
Swift
public static func callWithGvl(callback: () -> Void)