Threads

Compute-intensive tasks can be offloaded from the main emulation flow with threads. Unless otherwise stated, all structures, functions and constants in this page are provided by 86box/plat.h.

Warning

86Box API functions (excluding those in this page) are generally not thread-safe and must be called from the main emulation thread. Thread-unsafe actions (such as raising an interrupt) can be performed by the callback of a free-running timer which looks for data written to the device’s state structure by a thread, as timers run on the main emulation thread.

Note

The contents of thread_t and other structures used by thread_* functions are platform-specific; therefore, pointers to those structures should be treated as opaque pointers.

Starting

Threads can be started with the thread_create function. Additionally, the thread_wait function can be used to wait for a thread’s function to return.

thread_create

Parameter	Description
thread_func	Function to run in the thread. Takes the form of: void thread_func(void *priv) priv: opaque pointer (see priv below).
priv	Opaque pointer passed to the thread_func above. Usually a pointer to a device’s state structure.
Return value	thread_t pointer representing the newly-created thread. That pointer will become invalid once the thread’s function returns.

thread_wait

Parameter	Description
arg	thread_t pointer representing the thread to wait for.
Return value	0 on success; Any other value on failure.

Events

Events allow for synchronization between threads. An event, represented by an event_t pointer returned by the thread_create_event function, can be set (thread_set_event function) or reset (thread_reset_event function), and a thread can wait for an event to be set with the thread_wait_event function. Events that are no longer to be used should be deallocated with the thread_destroy_event function.

thread_create_event

Parameter	Description
Return value	event_t pointer representing the newly-created event.

thread_set_event / thread_reset_event / thread_destroy_event

Parameter	Description
arg	event_t pointer representing the event to set (thread_set_event), reset (thread_reset_event) or deallocate (thread_destroy_event).

thread_wait_event

Parameter	Description
arg	event_t pointer representing the event to wait for.
timeout	Maximum amount of time in milliseconds (not microseconds, unlike timers) to spend waiting for this event to be set. If set to -1, this function will not return until the event is set.
Return value	0 on success; Any other value if timeout was reached or the wait otherwise failed.

Note

A thread_wait_event call does not reset the event once it is set; the event must be reset manually with thread_reset_event. thread_wait_event returns immediately if the event is already set.

Mutexes

Mutexes, also known as locks, can control access to a shared resource, ensuring no concurrent modifications or other issues arise from multiple threads attempting to use the same resource at the same time. A mutex, represented by a mutex_t pointer returned by the thread_create_mutex function, can be locked with the thread_wait_mutex function (which waits until the mutex is released) and released with the thread_release_mutex function. Additionally, the status of a mutex can be independently checked with the thread_test_mutex function. Mutexes that are no longer to be used should be deallocated with the thread_close_mutex function.

thread_create_mutex

Parameter	Description
Return value	mutex_t pointer representing the newly-created mutex.

thread_wait_mutex / thread_release_mutex / thread_close_mutex

Parameter	Description
arg	mutex_t pointer representing the mutex to lock (thread_wait_mutex), release (thread_release_mutex) or deallocate (thread_close_mutex). If this mutex is locked, thread_wait_mutex will not return until the mutex is released by another thread.

thread_test_mutex

Parameter	Description
arg	mutex_t pointer representing the mutex to check.
Return value	0 if this mutex is locked; Any other value if the mutex is released.