►The Racket Foreign Interface
▼5 Derived Utilities
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    up   

5.10 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.

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    up