5.14 Operating System Threads

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Serializable C Struct Types
5.5 | Static Callout and Callback Cores
5.6 | Defining Bindings
5.7 | Allocation and Finalization
5.8 | Custodian Shutdown Registration
5.9 | Atomic Execution
5.10 | Speculatively Atomic Execution
5.11 | Thread Scheduling
5.12 | Ports
5.13 | Process-Wide and Place-Wide Registration
5.14 | Operating System Threads
5.15 | Garbage Collection Callbacks
5.16 | Objective-C FFI
5.17 | Cocoa Foundation
5.18 | COM (Common Object Model)
5.19 | File Security-Guard Checks
5.20 | Windows API Helpers
5.21 | Virtual Machine Primitives
5.22 | Declaring Foreign Libraries Needed at Run Time

► | 5.14 | Operating System Threads

5.14.1 | Operating System Asynchronous Channels

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

Racket
top contents ← prev up next →

### 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 coroutine threads, then waiting also blocks all other coroutine threads in the same place. Waiting from a parallel thread, does not necessarily block other Racket threads, but it consumes a processor resource for the thread’s pool, and it may block coroutine threads or others if they attempt to synchronize with the blocked parallel thread.

#### 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 ← prev up next →