Firelight Technologies FMOD Studio API

Threads and Thread Safety

Introduction

This section will describe the threads FMOD uses, and the thread safety offered by both the Studio API and the Low Level 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 a 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 Basic Information 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

FMOD Studio API Thread Safety

By default FMOD Studio API is completely thread safe and all commands will execute on the Studio thread. In the case of functions that return handles to the user, the handle will be valid as soon as the function returns it, and all functions using that handle will be available. Therefore, the fact that the commands have been delayed should be completely transparent to the user.

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.

FMOD Low Level API Thread Safety

By default FMOD Low Level API is initialized to be thread safe, which means the API can be called from any game thread at any time. Low Level 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:

• The game is using FMOD Studio API exclusively, and never issues Low Level calls itself.
• The game is using FMOD Low Level exclusively, and always from a single thread at once.
• The game is using FMOD Studio API and Low Level at the same time, but FMOD Studio is created with FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE and the Low Level calls are done in the same thread as the FMOD Studio calls.