►The Racket Foreign Interface
▼5 Derived Utilities
►5.14 Operating System Threads
On this page:
os-thread-enabled?
call-in-os-thread
make-os-semaphore
os-semaphore-post
os-semaphore-wait
5.14.1 Operating System Asynchronous Channels
make-os-async-channel
os-async-channel?
os-async-channel-put
os-async-channel-try-get
os-async-channel-get
  top  contents    up   

5.14 Operating System Threads🔗ℹ

 (require ffi/unsafe/os-thread) package: base
The ffi/unsafe/os-thread library provides functions for running constrained Racket code in a separate thread at the operating-system level. Except for os-thread-enabled?, the functions of ffi/unsafe/os-thread are currently supported only when (system-type 'vm) returns 'chez-scheme, and even then only in certain build modes. The functions raise exn:fail:unsupported when not supported.

Added in version 6.90.0.9 of package base.

procedure

(os-thread-enabled?) → boolean?

Returns #t if the other functions of ffi/unsafe/os-thread work without raising exn:fail:unsupported, #f otherwise.

procedure

(call-in-os-thread thunk) → void?

  thunk : (-> any)
Runs thunk in a separate operating-system thread, which runs concurrently to all Racket threads.

The thunk is run in atomic mode, and it must not inspect its continuation or use any Racket thread functions (such as thread or current-thread), any Racket synchronization functions (such as semaphore-post or sync), or any parameters (such as current-output-port). Variables may be safely mutated with set!, and vectors, mutable pairs, boxes, mutable structure fields, and eq?- and eqv?-based hash tables can be mutated, but the visibility of mutations to other threads is unspecified except as synchronized through os-semaphore-wait and os-semaphore-post.

procedure

(make-os-semaphore) → any

Creates a semaphore that can be used with os-semaphore-wait and os-semaphore-post to synchronize an operating-system thread with Racket threads and other operating-system threads.

procedure

(os-semaphore-post sema) → void?

  sema : any/c
Analogous to semaphore-post, but posts to a semaphore created by make-os-semaphore.

procedure

(os-semaphore-wait sema) → void?

  sema : any/c
Analogous to semaphore-wait, but waits on a semaphore created by make-os-semaphore. Waiting blocks the current thread; if the current thread is a Racket thread, then waiting also blocks all Racket threads.

5.14.1 Operating System Asynchronous Channels🔗ℹ

 (require ffi/unsafe/os-async-channel) package: base
The ffi/unsafe/os-async-channel library provides an asynchronous channels that work with operating-system threads, where normal racket channels or place channels are not allowed. These channels are typically used in combination with ffi/unsafe/os-thread.

An asynchronous operating-system channel is a synchronizable event, so can it can be used with sync to receive a value in a Racket thread. Other threads must use os-async-channel-try-get or os-async-channel-get.

When a thread is blocked on an otherwise inaccessible asynchronous channel that was produced by make-os-async-channel, the thread is not available for garbage collection. That’s different from a thread is blocked on a regular Racket channel or a place channel.

Added in version 8.0.0.4 of package base.

procedure

(make-os-async-channel) → os-async-channel?

Creates a new, empty asynchronous channel for use with operating-system threads.

procedure

(os-async-channel? v) → boolean?

  v : any/c
Returns #t if v is an asynchronous channel produced by make-os-async-channel, #f otherwise.

procedure

(os-async-channel-put ch v) → void?

  ch : os-async-channel?
  v : any/c
Enqueues v in the asynchronous channel ch. This function can be called from a Racket thread or any operating-system thread.

procedure

(os-async-channel-try-get ch [default-v]) → any/c

  ch : os-async-channel?
  default-v : any/c = #f
Dequeues a value from the the asynchronous channel ch and returns it, if a value is available. If no value is immediately available in the channel, default-v is returned. This function can be called from a Racket thread or any operating-system thread.

procedure

(os-async-channel-get ch) → any/c

  ch : os-async-channel?
Dequeues a value from the the asynchronous channel ch and returns it, blocking until a value is available. This function can be called from any non-Racket operating-system thread. This function should not be called from a Racket thread, since it blocks in a way that will block all Racket threads within a place; in a Racket thread, use sync, instead.

  top  contents    up