10 Threads

The initializer function scheme_basic_env creates the main Racket thread; all other threads are created through calls to scheme_thread.

Information about each internal Racket thread is kept in a Scheme_Thread structure. A pointer to the current thread’s structure is available as scheme_current_thread or from scheme_get_current_thread. A Scheme_Thread structure includes the following fields:

• error_buf — the mz_jmp_buf value used to escape from errors. The error_buf value of the current thread is available as scheme_error_buf.

• cjs.jumping_to_continuation — a flag that distinguishes escaping-continuation invocations from error escapes. The cjs.jumping_to_continuation value of the current thread is available as scheme_jumping_to_continuation.

• init_config — the thread’s initial parameterization. See also Parameterizations.

• cell_values — The thread’s values for thread cells (see also Parameterizations).

• next — The next thread in the linked list of threads; this is NULL for the main thread.

The list of all scheduled threads is kept in a linked list; scheme_first_thread points to the first thread in the list. The last thread in the list is always the main thread.

10.1 Integration with Threads

Racket’s threads can break external C code under two circumstances:

• Pointers to stack-based values can be communicated between threads. For example, if thread A stores a pointer to a stack-based variable in a global variable, if thread B uses the pointer in the global variable, it may point to data that is not currently on the stack.

• C functions that can invoke Racket (and also be invoked by Racket) depend on strict function-call nesting. For example, suppose a function F uses an internal stack, pushing items on to the stack on entry and popping the same items on exit. Suppose also that F invokes Racket to evaluate an expression. If the evaluation of this expression invokes F again in a new thread, but then returns to the first thread before completing the second F, then F’s internal stack will be corrupted.

If either of these circumstances occurs, Racket will probably crash.

10.2 Allowing Thread Switches

C code that performs substantial or unbounded work should occasionally call SCHEME_USE_FUEL—actually a macro—which allows Racket to swap in another Racket thread to run, and to check for breaks on the current thread. In particular, if breaks are enabled, then SCHEME_USE_FUEL may trigger an exception.

The macro consumes an integer argument. On most platforms, where thread scheduling is based on timer interrupts, the argument is ignored. On some platforms, however, the integer represents the amount of “fuel” that has been consumed since the last call to SCHEME_USE_FUEL. For example, the implementation of vector->list consumes a unit of fuel for each created cons cell:

The SCHEME_USE_FUEL macro expands to a C block, not an expression.

10.3 Blocking the Current Thread

Embedding or extension code sometimes needs to block, but blocking should allow other Racket threads to execute. To allow other threads to run, block using scheme_block_until. This procedure takes two functions: a polling function that tests whether the blocking operation can be completed, and a prepare-to-sleep function that sets bits in fd_sets when Racket decides to sleep (because all Racket threads are blocked). On Windows, an “fd_set” can also accommodate OS-level semaphores or other handles via scheme_add_fd_handle.

Since the functions passed to scheme_block_until are called by the Racket thread scheduler, they must never raise exceptions, call scheme_apply, or trigger the evaluation of Racket code in any way. The scheme_block_until function itself may call the current exception handler, however, in reaction to a break (if breaks are enabled).

When a blocking operation is associated with an object, then the object might make sense as an argument to sync. To extend the set of objects accepted by sync, either register polling and sleeping functions with scheme_add_evt, or register a semaphore accessor with scheme_add_evt_through_sema.

The scheme_signal_received function can be called to wake up Racket when it is sleeping. In particular, calling scheme_signal_received ensures that Racket will poll all blocking synchronizations soon afterward. Furthermore, scheme_signal_received can be called from any OS-level thread. Thus, when no adequate prepare-to-sleep function can be implemented for scheme_block_until in terms of file descriptors or Windows handles, calling scheme_signal_received when the poll result changes will ensure that a poll is issued.

10.4 Threads in Embedded Racket with Event Loops

When Racket is embedded in an application with an event-based model (i.e., the execution of Racket code in the main thread is repeatedly triggered by external events until the application exits) special hooks must be set to ensure that non-main threads execute correctly. For example, during the execution in the main thread, a new thread may be created; the new thread may still be running when the main thread returns to the event loop, and it may be arbitrarily long before the main thread continues from the event loop. Under such circumstances, the embedding program must explicitly allow Racket to execute the non-main threads; this can be done by periodically calling the function scheme_check_threads.

Thread-checking only needs to be performed when non-main threads exist (or when there are active callback triggers). The embedding application can set the global function pointer scheme_notify_multithread to a function that takes an integer parameter and returns void. This function is be called with 1 when thread-checking becomes necessary, and then with 0 when thread checking is no longer necessary. An embedding program can use this information to prevent unnecessary scheme_check_threads polling.

The below code illustrates how GRacket formerly set up scheme_check_threads polling using the wxWindows wxTimer class. (Any regular event-loop-based callback is appropriate.) The scheme_notify_multithread pointer is set to MrEdInstallThreadTimer. (GRacket no longer work this way, however.)

An alternate architecture, which GRacket now uses, is to send the main thread into a loop, which blocks until an event is ready to handle. Racket automatically takes care of running all threads, and it does so efficiently because the main thread blocks on a file descriptor, as explained in Blocking the Current Thread.

10.4.1 Callbacks for Blocked Threads

Racket threads are sometimes blocked on file descriptors, such as an input file or the X event socket. Blocked non-main threads do not block the main thread, and therefore do not affect the event loop, so scheme_check_threads is sufficient to implement this case correctly. However, it is wasteful to poll these descriptors with scheme_check_threads when nothing else is happening in the application and when a lower-level poll on the file descriptors can be installed. If the global function pointer scheme_wakeup_on_input is set, then this case is handled more efficiently by turning off thread checking and issuing a “wakeup” request on the blocking file descriptors through scheme_wakeup_on_input.

A scheme_wakeup_on_input procedure takes a pointer to an array of three fd_sets (use MZ_FD_SET instead of FD_SET, etc.) and returns void. The scheme_wakeup_on_input function does not sleep immediately; it just sets up callbacks on the specified file descriptors. When input is ready on any of those file descriptors, the callbacks are removed and scheme_wake_up is called.

For example, the X Windows version of GRacket formerly set scheme_wakeup_on_input to this MrEdNeedWakeup:

10.5 Sleeping by Embedded Racket

When all Racket threads are blocked, Racket must “sleep” for a certain number of seconds or until external input appears on some file descriptor. Generally, sleeping should block the main event loop of the entire application. However, the way in which sleeping is performed may depend on the embedding application. The global function pointer scheme_sleep can be set by an embedding application to implement a blocking sleep, although Racket implements this function for you.

A scheme_sleep function takes two arguments: a float and a void*. The latter is really points to an array of three “fd_set” records (one for read, one for write, and one for exceptions); these records are described further below. If the float argument is non-zero, then the scheme_sleep function blocks for the specified number of seconds, at most. The scheme_sleep function should block until there is input one of the file descriptors specified in the “fd_set,” indefinitely if the float argument is zero.

The second argument to scheme_sleep is conceptually an array of three fd_set records, but always use scheme_get_fdset to get anything other than the zeroth element of this array, and manipulate each “fd_set” with MZ_FD_SET, MZ_FD_CLR, etc. instead of FD_SET, FD_CLR, etc.

The following function mzsleep is an appropriate scheme_sleep function for most any Unix or Windows application. (This is approximately the built-in sleep used by Racket.)

10.6 Thread Functions

The config argument is typically obtained through scheme_current_config or scheme_extend_config. A config is immutable, so different threads can safely use the same value. The cells argument should be obtained from scheme_inherit_cells; it is mutable, and a particular cell table should be used by only one thread.

After calling this function, a program should almost always call scheme_making_progress next. The exception is when scheme_thread_block is called in a polling loop that performs no work that affects the progress of other threads. In that case, scheme_making_progress should be called immediately after exiting the loop.

See also scheme_block_until, and see also the SCHEME_USE_FUEL macro in Allowing Thread Switches.

Blocks the current thread until f with data returns a true value. The f function is called periodically—at least once per potential swap-in of the blocked thread—and it may be called multiple times even after it returns a true value. If f with data ever returns a true value, it must continue to return a true value until scheme_block_until returns. The argument to f is the same data as provided to scheme_block_until, and data is ignored otherwise. (The data argument is not actually required to be a Scheme_Object* value, because it is only used by f and fdf.)

If Racket decides to sleep, then the fdf function is called to sets bits in fds, conceptually an array of three fd_sets: one or reading, one for writing, and one for exceptions. Use scheme_get_fdset to get elements of this array, and manipulate an “fd_set” with MZ_FD_SET instead of FD_SET, etc. On Windows, an “fd_set” can also accommodate OS-level semaphores or other handles via scheme_add_fd_handle.

The fdf argument can be NULL, which implies that the thread becomes unblocked (i.e., ready changes its result to true) only through Racket actions, and never through external processes (e.g., through a socket or OS-level semaphore)—with the exception that scheme_signal_received may be called to indicate an external change.

If sleep is a positive number, then scheme_block_until polls f at least every sleep seconds, but scheme_block_until does not return until f returns a true value. The call to scheme_block_until can return before sleep seconds if f returns a true value.

The return value from scheme_block_until is the return value of its most recent call to f, which enables f to return some information to the scheme_block_until caller.

See Blocking the Current Thread for information about restrictions on the f and fdf functions.

As long as some threads are ready, this functions returns only after one thread quantum, at least.

Racket does not attempt to deallocate the given semaphore or handle, and the “select” call using fds may be unblocked due to some other file descriptor or handle in fds. If repost is a true value, then h must be an OS-level semaphore, and if the “select” unblocks due to a post on h, then h is reposted; this allows clients to treat fds-installed semaphores uniformly, whether or not a post on the semaphore was consumed by “select”.

The scheme_add_fd_handle function is useful for implementing the second procedure passed to scheme_wait_until, or for implementing a custom input port.

On Unix and Mac OS X, this function has no effect.

The event mask is only used when some handle is installed with scheme_add_fd_handle. This awkward restriction may force you to create a dummy semaphore that is never posted.

On Unix, and Mac OS X, this function has no effect.

Extends the set of waitable objects for sync to those with the type tag type. If filter is non-NULL, it constrains the new waitable set to those objects for which filter returns a non-zero value.

The ready and wakeup functions are used in the same way was the arguments to scheme_block_until.

The can_redirect argument should be 0.

If a successful wait should leave the semaphore waited, then getsema should set *repost to 0. Otherwise, the given semaphore will be re-posted after a successful wait. A getsema function should almost always set *repost to 1.