#include <mupnp/typedef.h>
#include <pthread.h>

Data Structures
struct	_mUpnpMutex
	The generic wrapper struct for mUPnP's mutexes. More...

Typedefs
typedef struct _mUpnpMutex	mUpnpMutex
	The generic wrapper struct for mUPnP's mutexes.

Functions
mUpnpMutex *	mupnp_mutex_new (void)
	Create a new mutex for synchronization.

bool	mupnp_mutex_delete (mUpnpMutex *mutex)
	Destroy a mutex and free resources.

bool	mupnp_mutex_lock (mUpnpMutex *mutex)
	Acquire a mutex lock (blocking)

bool	mupnp_mutex_unlock (mUpnpMutex *mutex)
	Release a previously acquired mutex lock.

Typedef Documentation

◆ mUpnpMutex

typedef struct _mUpnpMutex mUpnpMutex

The generic wrapper struct for mUPnP's mutexes.

This wrapper has been created to enable 100% code compatibility for different platforms (Linux, Win32 etc..)

Function Documentation

◆ mupnp_mutex_delete()

bool mupnp_mutex_delete ( mUpnpMutex * mutex )

Destroy a mutex and free resources.

Releases all resources associated with the mutex. The mutex must be unlocked before calling this function.

Parameters

mutex The mutex to destroy. May be NULL (no-op if NULL).

Return values

true	Successfully destroyed the mutex
false	Failed to destroy (e.g., mutex is NULL or still locked)

Note: After calling this function, the mutex pointer is invalid.; Thread-safe: Must not be called concurrently on the same mutex.; Must not be called while the mutex is locked; behavior is undefined and may cause deadlocks or resource leaks.

Warning: Destroying a locked mutex may cause undefined behavior on some platforms.

See also: mupnp_mutex_new()

◆ mupnp_mutex_lock()

bool mupnp_mutex_lock ( mUpnpMutex * mutex )

Acquire a mutex lock (blocking)

Attempts to lock the mutex. If the mutex is already locked by another thread, this function blocks (waits) until the mutex becomes available.

After successfully locking, the calling thread has exclusive access to the protected resource until mupnp_mutex_unlock() is called.

Mutexes are not recursive on all platforms. Attempting to lock the same mutex twice from the same thread may cause deadlock.

When WITH_THREAD_LOCK_TRACE is defined, this is replaced with a macro that enables lock tracing for debugging deadlocks and lock contention.

Parameters

mutex The mutex to lock. Must not be NULL.

Return values

true	Successfully acquired the lock
false	Failed to acquire lock (mutex is NULL or system error)

Note: Blocking behavior: This function will not return until the lock is acquired or an error occurs.; Thread-safe: Can be called from any thread.; Always pair with mupnp_mutex_unlock() and unlock as soon as possible to minimize lock contention.; On most platforms, mutexes are not recursive. Do not attempt to lock the same mutex twice from the same thread.

Warning: Failing to unlock a locked mutex will cause other threads to block indefinitely (deadlock).; Do not call this function from signal handlers or with interrupts disabled.

See also: mupnp_mutex_unlock(); mupnp_mutex_new()

◆ mupnp_mutex_new()

mUpnpMutex * mupnp_mutex_new ( void )

Create a new mutex for synchronization.

Allocates and initializes a platform-independent mutex object. Mutexes are used to protect shared resources and ensure thread-safe access to data structures across the mUPnP library.

The mutex is initially unlocked and ready to use.

Platform support:

Linux/Unix: pthread_mutex_t
Windows: HANDLE (CreateMutex)
ITRON, T-Engine, BTRON: platform-specific mutex primitives

Returns: A newly-created mUpnpMutex on success, or NULL if mutex creation fails (e.g., insufficient system resources).

Note: The returned mutex must be freed with mupnp_mutex_delete() when no longer needed to avoid resource leaks.; Thread-safe: Can be called concurrently from multiple threads.; On some platforms, there may be system limits on the number of mutexes that can be created.

See also: mupnp_mutex_delete(); mupnp_mutex_lock(); mupnp_mutex_unlock()

// Example: Protect a shared counter
static int shared_counter = 0;
static mUpnpMutex* counter_mutex = NULL;
 
void init() {
    counter_mutex = mupnp_mutex_new();
}
 
void increment_counter() {
    mupnp_mutex_lock(counter_mutex);
    shared_counter++;
    mupnp_mutex_unlock(counter_mutex);
}
 
void cleanup() {
    mupnp_mutex_delete(counter_mutex);
}

◆ mupnp_mutex_unlock()

bool mupnp_mutex_unlock ( mUpnpMutex * mutex )

Release a previously acquired mutex lock.

Unlocks a mutex that was previously locked with mupnp_mutex_lock(). This allows other threads waiting on the mutex to acquire the lock.

The mutex must be locked by the calling thread before calling this function. Unlocking a mutex that is not locked or is locked by a different thread results in undefined behavior.

When WITH_THREAD_LOCK_TRACE is defined, this is replaced with a macro that enables lock tracing for debugging.

Parameters

mutex The mutex to unlock. Must not be NULL and must be locked by the calling thread.

Return values

true	Successfully released the lock
false	Failed to unlock (mutex is NULL, not locked, or system error)

Note: Thread-safe: Can be called from any thread, but must be the thread that acquired the lock.; Always call this function after mupnp_mutex_lock() as soon as the protected operation is complete.; Unlock must be called from the same thread that acquired the lock.

Warning: Unlocking a mutex from a different thread than the one that locked it results in undefined behavior.; Unlocking an already unlocked mutex results in undefined behavior.

See also: mupnp_mutex_lock(); mupnp_mutex_new()

Data Structures

Typedefs

Functions

Typedef Documentation

◆ mUpnpMutex

Function Documentation

◆ mupnp_mutex_delete()

◆ mupnp_mutex_lock()

◆ mupnp_mutex_new()

◆ mupnp_mutex_unlock()