Mutex handling

Description

Historically, the OSystem API used to have a method that allowed creating threads. Hence, mutex support was needed for thread syncing. To ease portability, we decided to remove the threading API. Instead, we now use timers (see setTimerCallback() and Common::Timer). But since those can be implemented using threads (and in fact, that is how our primary backend, the SDL one, does it on many systems), we still must do mutex syncing in our timer callbacks. In addition, the sound mixer uses a mutex in case the backend runs it from a dedicated thread (as the SDL backend does).

Hence, backends that do not use threads to implement the timers can simply use dummy implementations for these methods.

Typedefs
typedef struct OpaqueMutex *	OSystem::MutexRef

Functions
virtual MutexRef	OSystem::createMutex ()=0
virtual void	OSystem::lockMutex (MutexRef mutex)=0
virtual void	OSystem::unlockMutex (MutexRef mutex)=0
virtual void	OSystem::deleteMutex (MutexRef mutex)=0

Function Documentation

createMutex()

virtual MutexRef OSystem::createMutex ( )

pure virtual

Create a new mutex.

Returns

The newly created mutex, or 0 if an error occurred.

lockMutex()

virtual void OSystem::lockMutex ( MutexRef  mutex )

pure virtual

Lock the given mutex.

Note

ScummVM code assumes that the mutex implementation supports recursive locking. That is, a thread can lock a mutex twice without deadlocking. In case of a multilock, the mutex must be unlocked as many times as it was locked befored it really becomes unlocked.

Parameters

mutex

The mutex to lock.

unlockMutex()

virtual void OSystem::unlockMutex ( MutexRef  mutex )

pure virtual

Unlock the given mutex.

Parameters

mutex

The mutex to unlock.

deleteMutex()

virtual void OSystem::deleteMutex ( MutexRef  mutex )

pure virtual

Delete the given mutex.

Make sure the mutex is unlocked before you delete it. If you delete a locked mutex, the behavior is undefined. In particular, your program may crash.

Parameters

mutex

The mutex to delete.