5.11 Thread Scheduling

► |  | 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

On this page:

unsafe-poller
unsafe-poll-fd
unsafe-poll-ctx-fd-wakeup
unsafe-poll-ctx-eventmask-wakeup
unsafe-poll-ctx-milliseconds-wakeup
unsafe-set-sleep-in-thread!
unsafe-signal-received
unsafe-make-signal-received

top contents ← prev up next →

### 5.11 Thread Scheduling🔗ℹ

(require ffi/unsafe/schedule) | package: base

The ffi/unsafe/schedule library provides functions for cooperating with the thread scheduler and manipulating it. The library’s operations are unsafe because callbacks run in atomic mode and in an unspecified thread.

Running an operation in an unspecified thread means that the Racket scheduler for coroutine threads selects a convenient coroutine thread and switches the thread’s evaluation temporarily to the operation. The thread will not have been in atomic mode, but the operation using the thread is always run in atomic mode. An operation that is run in an unspecified thread can use (current-thread) check parameter values, and inspect the continuation, but doing so is unsafe: the current thread and its continuation are not specified, and misusing a thread or it continuation can leak information or change the thread’s behavior.

Added in version 6.11.0.1 of package base.

> procedure (unsafe-poller poll) → any/c
> poll : (evt? (or/c #f any/c) . -> . (values (or/c #f list?) evt?))

Produces a poller value that is allowed as a prop:evt value, even though it is not a procedure or itself an evt?. The poll callback is called in atomic mode in an unspecified thread to check whether the event is ready or to allow it to register a wakeup trigger.

The first argument to poll is always the object that is used as a synchronizable event with the poller as its prop:evt value. Let’s call that value evt.

The second argument to poll is #f when poll is called to check whether the event is ready. The result must be two values. The first result value is a list of results if evt is ready, or it is #f if evt is not ready. The second result value is #f if evt is ready, or it is an event to replace evt (often just evt itself) if evt is not ready.

When the thread scheduler has determined that the Racket process should sleep until an external event or timeout, then poll is called with a non-#f second argument, wakeups. In that case, if the first result value is a list, then the sleep will be canceled, but the list is not recorded as the result (and poll most likely will be called again). In addition to returning a #f initial value, poll can call unsafe-poll-ctx-fd-wakeup, unsafe-poll-ctx-eventmask-wakeup, and/or unsafe-poll-ctx-milliseconds-wakeup on wakeups to register wakeup triggers.

> procedure (unsafe-poll-fd fd mode [socket?]) → boolean?
> fd : exact-integer?
> mode : '(read write)
> socket? : any/c = #t

Checks whether the given file descriptor or socket is currently ready for reading or writing, as selected by mode.

Added in version 7.2.0.6 of package base.

> procedure (unsafe-poll-ctx-fd-wakeup wakeups fd mode) → void?
> wakeups : any/c
> fd : fixnum?
> mode : '(read write error)

Registers a file descriptor (Unix and Mac OS) or socket (all platforms) to cause the Racket process to wake up and resume polling if the file descriptor or socket becomes ready for reading, writing, or error reporting, as selected by mode. The wakeups argument must be a non-#f value that is passed by the scheduler to a unsafe-poller-wrapped procedure.

> > procedure
> > (unsafe-poll-ctx-eventmask-wakeup |  | wakeups |  |  |  |
> > |  | mask) |  | → |  | void?
> wakeups : any/c
> mask : fixnum?

On Windows, registers an eventmask to cause the Racket process to wake up and resume polling if an event selected by the mask becomes available.

> > procedure
> > (unsafe-poll-ctx-milliseconds-wakeup |  | wakeups |  |  |  |
> > |  | msecs) |  | → |  | void?
> wakeups : any/c
> msecs : flonum?

Causes the Racket process to wake up and resume polling at the point when (current-inexact-monotonic-milliseconds) starts returning a value that is msecs or greater.

Changed in version 8.3.0.9 of package base: unsafe-poll-ctx-milliseconds-wakeup previously used current-inexact-milliseconds.

> > procedure
> > (unsafe-set-sleep-in-thread! |  | foreground-sleep |  |  |  |
> > |  | fd) |  | → |  | void?
> foreground-sleep : (-> any/c)
> fd : fixnum?

Registers foreground-sleep as a procedure to implement sleeping for the Racket process when the thread scheduler determines at the process will sleep. Meanwhile, during a call to foreground-sleep, the scheduler’s default sleeping function will run in a separate OS-level thread. When that default sleeping function wakes up, a byte is written to fd as a way of notifying foreground-sleep that it should return immediately.

This function works on when OS-level threads are available within the Racket implementation. It always works for Mac OS.

> procedure (unsafe-signal-received) → void?

For use with unsafe-set-sleep-in-thread! by foreground-sleep or something that it triggers, causes the default sleeping function to request foreground-sleep to return.

> procedure (unsafe-make-signal-received) → (-> void?)

Returns a function that is like unsafe-signal-received, but it can be called in any place or in any OS thread as supported by ffi/unsafe/os-thread to ensure a subsequent round of polling by the thread scheduler in the place where unsafe-make-signal-received was called.

Synchronizaiton between the result of unsafe-make-signal-received and the scheduler will ensure the equivalent of (memory-order-release) before the call to the function produced by unsafe-make-signal-received and the equivalent of (memory-order-acquire) before the scheduler’s invocation of pollers.

Added in version 8.0.0.4 of package base.

top contents ← prev up next →