FMOD Engine User Manual 2.03

5. White Papers | Threads and Thread Safety

Threads and Thread Safety

This section will describe the threads FMOD uses, and the thread safety offered by both the Studio API and the Core API.

FMOD Thread Types

Studio Thread

This thread processes all Studio API commands and updates Studio events. It is created during Studio::System::initialize by default, unless FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE is specified as an init flag.

Mixer Thread

This thread is the software mixing thread. This is the thread that does the real work of mixing the DSP graph. It is created at System::init.

Stream Thread

This thread is used for decoding streams. It is created the first time a sound is loaded as a stream in System::createSound with FMOD_CREATESTREAM, or System::createStream.

Async Loading Thread

This thread is created the first time a sound is loaded with the FMOD_NONBLOCKING flag in System::createSound.

File Reading Thread

This thread is used for reading from disk for streams, to then be decoded (decompressed) by the Stream thread. It is created the first time a sound is loaded as a stream in System::createSound with FMOD_CREATESTREAM, or System::createStream.

Thread Affinity

On some platforms, FMOD thread affinity can be customised. See the platform specific Platform Details page for more information.

FMOD Callback Types

FMOD File and memory callbacks can possibly be called from an FMOD thread. Remember that if you specify file or memory callbacks with FMOD, to make sure that they are thread safe. FMOD may call these callbacks from other threads.

FMOD Thread Safety

Studio API Thread Safety

By default, the Studio API is completely thread safe, and all commands execute on the Studio API update thread. In the case of a function that returns a handle, that handle is valid as soon as the function returns it, and all functions using that handle are immediately available. As such, if a command is delayed, the delay is not immediately obvious, and does not delay subsequent commands on the thread.

If Studio::System::initialize is called with FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE, then Studio will not be thread-safe as it assumes all calls will be issued from a single thread. Commands in this mode will be queued up to be processed in the next Studio::System::update call. This mode is not recommended except for testing or for users who have set up their own asynchronous command queue already and wish to process all calls on a single thread. See the Studio Thread Overview for further information.

Core API Thread Safety

By default, the Core API is initialized to be thread safe, which means the API can be called from any game thread at any time. Core API thread safety can be disabled with the FMOD_INIT_THREAD_UNSAFE flag in System::init or Studio::System::initialize. The overhead of thread safety is that there is a mutex lock around the public API functions and (where possible) some commands are enqueued to be executed the next system update. The cases where it is safe to disable thread safety are: