Library Functions

Scheme_Object *scheme_thread(Scheme_Object *thunk, Scheme_Config *config) 

Creates a new thread, using the given parameterization for the new thread. If config is NULL, a new parameterization is created using the current thread's parameterization's current base parameterization. The new thread begins evaluating the application of the procedure thunk (with no arguments).

Scheme_Object *scheme_make_sema(long v) 

Creates a new semaphore.

void scheme_post_sema(Scheme_Object *sema) 

Posts to sema.

int scheme_wait_sema(Scheme_Object *sema, int try) 

Waits on sema. If try is not 0, the wait can fail and 0 is returned for failure, otherwise 1 is returned.

void scheme_process_block(float sleep_time) 

Allows the current thread to be swapped out in favor of other threads. If sleep_time positive, then the current thread will sleep for at least sleep_time seconds.

void scheme_swap_process(Scheme_Process *process) 

Swaps out the current thread in favor of process.

void scheme_break_thread(Scheme_Process *thread) 

Issues a user-break in the given thread.

int scheme_break_waiting(Scheme_Process *thread) 

Returns 1 if a break from break-thread or scheme_break_thread has occured in the specified process but has not yet been handled.

int scheme_block_until(int (*f)(Scheme_Object *data), 
    void (*fdf)(Scheme_Object *data, void *fds), void *data, float sleep) 

Blocks the current thread until f returns a true value. The f function is called periodically, and it may be called multiple times even after it returns a true value. (If f ever returns a true value, it must continue to return a true value.) The argument to f is the same data as provided to scheme_block_until, and data is ignored otherwise. (The type mismatch between void* and Scheme_Object* is an ugly artifact. The data argument is not intended to necessarily be a Scheme_Object* value.)

If MzScheme 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_XXX instead of FD_XXX. Under Windows and BeOS, an ``fd_set'' can also accomodate OS-level semaphores or other handles via scheme_add_fd_handle.

The fdf argument can be NULL, indicating that the thread becomes unblocked only through Scheme actions, and never through external processes (e.g., through a socket or OS-level semaphore).

If sleep is a positive number, then scheme_block_until polls f roughly every sleep seconds, but scheme_block_until does not return until 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 section 2.7.2 for information about restrictions on the f and fdf functions.

void scheme_check_threads() 

This function is periodically called by the embedding program to give background processes time to execute. See section 2.7.3 for more information.

void scheme_wake_up() 

This function is called by the embedding program when there is input on an external file descriptor. See section 2.7.4 for more information.

void *scheme_get_fdset(void *fds) 

Extracts an ``fd_set'' from an array passed to scheme_sleep, a callback for scheme_block_until, or an input port callback for scheme_make_input_port.

void scheme_add_fd_handle(void *h, void *fds, int repost) 

Adds an OS-level semaphore (Windows, BeOS) or other waitable handle (Windows) to the ``fd_set'' fds. When MzScheme performs a ``select'' to sleep on fds, it also waits on the given semaphore or handle. This feature makes it possible for MzScheme to sleep until it is awakened by an external process.

MzScheme 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 semeaphore, 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.

Under Unix and MacOS, this function has no effect.

void scheme_add_fd_eventmask(void *fds, int mask) 

Adds an OS-level event type (Windows) to the set of types in the ``fd_set'' fds. When MzScheme performs a ``select'' to sleep on fds, it also waits on events of them specified type. This feature makes it possible for MzScheme to sleep until it is awakened by an external process.

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

Under Unix, BeOS, and MacOS, this function has no effect.

int scheme_tls_allocate() 

Allocates a thread local storage index to be used with scheme_tls_set and scheme_tls_get.

void scheme_tls_set(int index, void *v) 

Stores a thread-specific value using an index allocated with scheme_tls_allocate.

void *scheme_tls_get(int index) 

Retrieves a thread-specific value installed with scheme_tls_set. If no thread-specific value is available for the given index, NULL is returned.