---
name: "rthread_mutex"
section: "3"
platform: "linux"
package: "libroy-dev"
version: "1.0.8-1"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/rthread_mutex"
---

# rthread\_mutex(3)

Roy threading API

## NAME

rthread - Roy threading API

## SYNOPSIS

\#include \<roy.h\>

RThreadMutex rthread\_mutex\_new (void);

int rthread\_mutex\_lock (RThreadMutex mutex);

int rthread\_mutex\_trylock (RThreadMutex mutex);

int rthread\_mutex\_unlock (RThreadMutex mutex);

void rthread\_mutex\_destroy (RThreadMutex mutex);

RTHREAD\_MUTEX\_ENTER(mutex)

RTHREAD\_MUTEX\_EXIT(mutex)

## DESCRIPTION

These functions add mutex support to the RThread API.  Mutex stands for mutual exclusion and allows only one thread at a time to enter  a peice of code protected by one.  These are often used to protect global and static variables and data structures from simultaneous modification.

Mutex locking should always be balanced; that is, one lock for every unlock.  While this is not a requirement on many pthread implementations, it is required on Win32.

The RTHREAD\_MUTEX\_ENTER/EXIT macros are to be used as a pair within a single function and require opening and closing braces around the code they are to protect.  This gives a nice, forced balance to mutexes.   For example:

RTHREAD\_MUTEX\_ENTER(mutex) {\
     ... code ... } RTHREAD\_MUTEX\_EXIT(mutex);

*rthread\_mutex\_new*(3) initializes a mutex for use.  Note the lack of a pointer for this type.  This is intentional as the type is defined differently on different platforms.  You must always declare the mutex without a pointer.

*rthread\_mutex\_lock*(3) locks the mutex so that no other threads may enter.  This call may block until the previous thread has exited the mutex (if necessary).

*rthread\_mutex\_trylock*(3) will not block if the mutex is in use and will simply return non-zero in the event that the lock is already in use.

*rthread\_mutex\_unlock*(3) will unlock a mutex allowing others to enter.

*rthread\_mutex\_destroy*(3) will destroy a mutex and free any storage associated with it.

## RETURN VALUES

All functions returning an *int* return 0 on success, or non-zero on failure.

## SEE ALSO

[*roy*(3)](/roy/3.md), [*rthread*(3)](/rthread/3.md),  [*rthread\_event*(3)](/rthread_event/3.md)