►Rhombus Reference
▼15 Threads and Concurrency
On this page:
Thread
thread
Thread.Keep
Thread.Keep.results
Thread.current
Thread.wait
Thread.break
Thread.Break
Thread.Break.interrupt
Thread.Break.hang_  up
Thread.Break.terminate
Thread.kill
Thread.send
Thread.receive
Thread.maybe_  receive
Thread.receive_  evt
Thread.handle
Thread.from_  handle
Thread.sleep
Thread.Pool
Thread.Pool.close
Thread.Pool.own
Thread.Pool.processor_  count
Thread.Pool.handle
Thread.Pool.from_  handle
0.45+9.2.0.3
Rhombus
  top  contents    up   

15.1 Threads🔗ℹ

A thread is a concurrent thread of evaluation. Rhombus schedules threads preemptively, but conceptually on the same physical processor as a coroutine thread by default; coroutine threads provide concurrency, but not parallelism. Create a parallel thread by specifying a parallel thread pool when creating the thread. Threads can communicate via shared state, and they can synchronize using semaphores or other synchronizable events.

A Thread object is itself a synchronizable event that is ready for synchronization when the thread has terminated. The synchronization result is just the thread object itself.

class

class Thread():

  constructor (

    thunk :: Function.of_arity(0),

    ~pool: pool :: maybe(Thread.Pool || Any.of(#'own)) = #false,

    ~keep: keep :: maybe(Thread.Keep) = ~false

  )

 

expression

thread:

  option; ...

  body

  ...

 

option

 = 

~pool: pool_body; ...

 | 

~keep: keep_body; ...

 

enumeration

enum Thread.Keep

| results

The Thread class represents a thread. The Thread constructor accepts a function to call in a newly created thread.

If pool is #false, then the thread is created as a coroutine thread. If pool is a Thread.Pool, then the thread is created as a parallel thread in the given pool. Supplying #'own as pool is equivalent to supplying Thread.Pool(1), but also closing the pool with Thread.Pool.close immediately after the new thread is added.

If keep is #false, then the result of thunk is ignored. If keep is #'results, then the results from thunk are saved and returned by Thread.wait on the thread.

A thread: body; ... form is equivalent to Thread(fun (): body; ...). Using a ~pool or ~keep option in thread is the same as passing the corresponding argument to the Thread constructor.

A Thread object satisfies Evt and includes the Evt.sync method.

function

fun Thread.current() :: Thread

Returns an object representing the current thread.

Calling Thread.current multiple times within a thread returns objects that are ==, but they may not be ===.

method

method (th :: Thread).wait(

  fail_k :: Function.of_arity(0) = Function.pass

) :: Any

Blocks until the thread th terminates.

If the thread completes normally—without throwing an exception of otherwise aborting to the thunk’s initial prompt—then the results are any results saved by the thread (because it was created with ~keep: #'results) or #void if results are not kept.

If the thread does not complete normally, then fail_k is called in tail position, so its results are the results of Thread.wait.

> def th:

    thread:

      ~keep: #'results

      1 + 2

> th.wait()

3

method

method (th :: Thread).break(

  kind :: Thread.Break = #'interrupt

) :: Void

 

enumeration

enum Thread.Break

| interrupt

| hang_up

| terminate

Asynchronously throws an Exn.Break exception in th, assuming that it has not yet terminated. If kind is #'hang_up or #'terminate, then the exception is more specifically Exn.Break.HangUp or Exn.Break.Terminate, respectively.

method

method (th :: Thread).kill() :: Void

Terminates the thread th. If the thread has already terminated, then Thread.kill has no effect.

method

method (th :: Thread).send(

  v :: Any,

  ~fail: fail :: maybe(() -> ~any) = #false

)

 

function

fun Thread.receive()

 

function

fun Thread.maybe_receive()

 

function

fun Thread.receive_evt() :: Evt

Each thread has a mailbox to receive messages, where each message can be any Rhombus value.

The Thread.send method queues a message for th. As long as th is still running, Thread.send immediately returns #void. If th has stopped running and fail is a function, it is called and its returned is returned. If th has stopped running and fail is #false, the result is #false.

The Thread.receive function blocks until the current thread has a message, and then it dequeues and returns that message. The Thread.maybe_receive function either dequeues and returns an immediately available message, or it returns #false immediately if no message is queued. The Thread.receive_evt function returns a synchronizable event that is ready when the current thread has a message; the event’s synchronization result is itself.

The Thread.receive, Thread.maybe_receive, and Thread.receive_evt functions are not methods, because a thread can only receive messages to itself, so Thread.current() is implicit.

> def orig = Thread.current()

> def t:

    thread:

      match Thread.receive()

      | #'ping: orig.send(#'pong)

> Thread.maybe_receive()

#false

> t.send(#'ping)

> Thread.receive()

#'pong

> t.wait()

> t.send(#'oops, ~fail: fun (): "thread isn't there")

"thread isn't there"

property

property (th :: Thread).handle

 

function

fun Thread.from_handle(handle) :: Thread

The Thread.handle property accesses a thread object’s underlying Racket representation. The Thread.from_handle function constructs a Rhombus thread object from a Racket thread object.

function

fun Thread.sleep(secs :: NonnegReal) :: Void

Causes the current thread to pause for at least secs seconds.

class

class Thread.Pool():

  constructor(n :: PosInt = Thread.Pool.processor_count())

 

method

method (pool :: Thread.Pool).close() :: Void

 

value

def Thread.Pool.own = #'own

The Thread.Pool class represents a parallel thread pool. Threads in the same pool share processor resources so that up to n threads run in parallel to each other and other threads. All threads (in the pool and otherwise) run concurrently to each other.

A thread can be added to a pool as long as the pool is still open. After Thread.Pool.close is called on a pool, no new threads can be added to the pool, and the pool’s resources are released back to the system a threads already within the pool terminate.

The Thread.Pool.own value #'own is useful with ~pool in thread.

function

fun Thread.Pool.processor_count() :: PosInt

Returns the total number of processors available on the current machine. A thread pool larger than this result is unlikely to offer any benefit over a pool whose size matches the result.

property

property (th :: Thread.Pool).handle

 

function

fun Thread.Pool.from_handle(handle) :: Thread.Pool

The Thread.Pool.handle property accesses a thread pool object’s underlying Racket representation. The Thread.from_handle function constructs a Rhombus thread pool object from a Racket thread pool object.

  top  contents    up