synchronization.h File Reference

Provides synchronization locks. More...

`#include <sys/lock.h>`
`#include <3ds/svc.h>`

Go to the source code of this file.

## Data Structures

struct | LightEvent
| A light event. More...
struct | LightSemaphore
| A light semaphore. More...

## Macros

#define | AtomicIncrement(ptr) __atomic_add_fetch((u32*)(ptr), 1, __ATOMIC_SEQ_CST)
| Performs an atomic pre-increment operation.
#define | AtomicDecrement(ptr) __atomic_sub_fetch((u32*)(ptr), 1, __ATOMIC_SEQ_CST)
| Performs an atomic pre-decrement operation.
#define | AtomicPostIncrement(ptr) __atomic_fetch_add((u32*)(ptr), 1, __ATOMIC_SEQ_CST)
| Performs an atomic post-increment operation.
#define | AtomicPostDecrement(ptr) __atomic_fetch_sub((u32*)(ptr), 1, __ATOMIC_SEQ_CST)
| Performs an atomic post-decrement operation.
#define | AtomicSwap(ptr, value) __atomic_exchange_n((u32*)(ptr), (value), __ATOMIC_SEQ_CST)
| Performs an atomic swap operation.

## Typedefs

typedef _LOCK_T | LightLock
| A light lock.
typedef _LOCK_RECURSIVE_T | RecursiveLock
| A recursive lock.
typedef s32 | CondVar
| A condition variable.

## Functions

static void | __dsb (void)
| Performs a Data Synchronization Barrier operation.
static void | __dmb (void)
| Performs a Data Memory Barrier operation.
static void | __isb (void)
| Performs an Instruction Synchronization Barrier (officially "flush prefetch buffer") operation.
static void | __clrex (void)
| Performs a clrex operation.
static s32 | __ldrex (s32 *addr)
| Performs a ldrex operation. More...
static bool | __strex (s32 *addr, s32 val)
| Performs a strex operation. More...
static u16 | __ldrexh (u16 *addr)
| Performs a ldrexh operation. More...
static bool | __strexh (u16 *addr, u16 val)
| Performs a strexh operation. More...
static u8 | __ldrexb (u8 *addr)
| Performs a ldrexb operation. More...
static bool | __strexb (u8 *addr, u8 val)
| Performs a strexb operation. More...
Result | syncArbitrateAddress (s32 *addr, ArbitrationType type, s32 value)
| Function used to implement user-mode synchronization primitives. More...
Result | syncArbitrateAddressWithTimeout (s32 *addr, ArbitrationType type, s32 value, s64 timeout_ns)
| Function used to implement user-mode synchronization primitives (with timeout). More...
void | LightLock_Init (LightLock *lock)
| Initializes a light lock. More...
void | LightLock_Lock (LightLock *lock)
| Locks a light lock. More...
int | LightLock_TryLock (LightLock *lock)
| Attempts to lock a light lock. More...
void | LightLock_Unlock (LightLock *lock)
| Unlocks a light lock. More...
void | RecursiveLock_Init (RecursiveLock *lock)
| Initializes a recursive lock. More...
void | RecursiveLock_Lock (RecursiveLock *lock)
| Locks a recursive lock. More...
int | RecursiveLock_TryLock (RecursiveLock *lock)
| Attempts to lock a recursive lock. More...
void | RecursiveLock_Unlock (RecursiveLock *lock)
| Unlocks a recursive lock. More...
void | CondVar_Init (CondVar *cv)
| Initializes a condition variable. More...
void | CondVar_Wait (CondVar *cv, LightLock *lock)
| Waits on a condition variable. More...
int | CondVar_WaitTimeout (CondVar *cv, LightLock *lock, s64 timeout_ns)
| Waits on a condition variable with a timeout. More...
void | CondVar_WakeUp (CondVar *cv, s32 num_threads)
| Wakes up threads waiting on a condition variable. More...
static void | CondVar_Signal (CondVar *cv)
| Wakes up a single thread waiting on a condition variable. More...
static void | CondVar_Broadcast (CondVar *cv)
| Wakes up all threads waiting on a condition variable. More...
void | LightEvent_Init (LightEvent *event, ResetType reset_type)
| Initializes a light event. More...
void | LightEvent_Clear (LightEvent *event)
| Clears a light event. More...
void | LightEvent_Pulse (LightEvent *event)
| Wakes up threads waiting on a sticky light event without signaling it. More...
void | LightEvent_Signal (LightEvent *event)
| Signals a light event, waking up threads waiting on it. More...
int | LightEvent_TryWait (LightEvent *event)
| Attempts to wait on a light event. More...
void | LightEvent_Wait (LightEvent *event)
| Waits on a light event. More...
int | LightEvent_WaitTimeout (LightEvent *event, s64 timeout_ns)
| Waits on a light event until either the event is signaled or the timeout is reached. More...
void | LightSemaphore_Init (LightSemaphore *semaphore, s16 initial_count, s16 max_count)
| Initializes a light semaphore. More...
void | LightSemaphore_Acquire (LightSemaphore *semaphore, s32 count)
| Acquires a light semaphore. More...
int | LightSemaphore_TryAcquire (LightSemaphore *semaphore, s32 count)
| Attempts to acquire a light semaphore. More...
void | LightSemaphore_Release (LightSemaphore *semaphore, s32 count)
| Releases a light semaphore. More...

## Detailed Description

Provides synchronization locks.

## Function Documentation

## __ldrex()

static s32 __ldrex | ( | s32 * | addr | ) |

inlinestatic

Performs a ldrex operation.

Parameters

  addr | Address to perform the operation on.

Returns
  The resulting value.

## __ldrexb()

static u8 __ldrexb | ( | u8 * | addr | ) |

inlinestatic

Performs a ldrexb operation.

Parameters

  addr | Address to perform the operation on.

Returns
  The resulting value.

## __ldrexh()

static u16 __ldrexh | ( | u16 * | addr | ) |

inlinestatic

Performs a ldrexh operation.

Parameters

  addr | Address to perform the operation on.

Returns
  The resulting value.

## __strex()

static bool __strex | ( | s32 * | addr,
|  | s32 | val
| ) |  |

inlinestatic

Performs a strex operation.

Parameters

  addr | Address to perform the operation on.
  val | Value to store.

Returns
  Whether the operation was successful.

## __strexb()

static bool __strexb | ( | u8 * | addr,
|  | u8 | val
| ) |  |

inlinestatic

Performs a strexb operation.

Parameters

  addr | Address to perform the operation on.
  val | Value to store.

Returns
  Whether the operation was successful.

## __strexh()

static bool __strexh | ( | u16 * | addr,
|  | u16 | val
| ) |  |

inlinestatic

Performs a strexh operation.

Parameters

  addr | Address to perform the operation on.
  val | Value to store.

Returns
  Whether the operation was successful.

## CondVar_Broadcast()

static void CondVar_Broadcast | ( | CondVar * | cv | ) |

inlinestatic

Wakes up all threads waiting on a condition variable.

Parameters

  cv | Pointer to the condition variable.

## CondVar_Init()

void CondVar_Init | ( | CondVar * | cv | ) |

Initializes a condition variable.

Parameters

  cv | Pointer to the condition variable.

## CondVar_Signal()

static void CondVar_Signal | ( | CondVar * | cv | ) |

inlinestatic

Wakes up a single thread waiting on a condition variable.

Parameters

  cv | Pointer to the condition variable.

## CondVar_Wait()

void CondVar_Wait | ( | CondVar * | cv,
|  | LightLock * | lock
| ) |  |

Waits on a condition variable.

Parameters

  cv | Pointer to the condition variable.
  lock | Pointer to the lock to atomically unlock/relock during the wait.

## CondVar_WaitTimeout()

int CondVar_WaitTimeout | ( | CondVar * | cv,
|  | LightLock * | lock,
|  | s64 | timeout_ns
| ) |  |

Waits on a condition variable with a timeout.

Parameters

  cv | Pointer to the condition variable.
  lock | Pointer to the lock to atomically unlock/relock during the wait.
  timeout_ns | Timeout in nanoseconds.

Returns
  Zero on success, non-zero on failure.

## CondVar_WakeUp()

void CondVar_WakeUp | ( | CondVar * | cv,
|  | s32 | num_threads
| ) |  |

Wakes up threads waiting on a condition variable.

Parameters

  cv | Pointer to the condition variable.
  num_threads | Maximum number of threads to wake up (or ARBITRATION_SIGNAL_ALL to wake them all).

## LightEvent_Clear()

void LightEvent_Clear | ( | LightEvent * | event | ) |

Clears a light event.

Parameters

  event | Pointer to the event.

## LightEvent_Init()

void LightEvent_Init | ( | LightEvent * | event,
|  | ResetType | reset_type
| ) |  |

Initializes a light event.

Parameters

  event | Pointer to the event.
  reset_type | Type of reset the event uses (RESET_ONESHOT/RESET_STICKY).

## LightEvent_Pulse()

void LightEvent_Pulse | ( | LightEvent * | event | ) |

Wakes up threads waiting on a sticky light event without signaling it.

If the event had been signaled before, it is cleared instead.

Parameters

  event | Pointer to the event.

## LightEvent_Signal()

void LightEvent_Signal | ( | LightEvent * | event | ) |

Signals a light event, waking up threads waiting on it.

Parameters

  event | Pointer to the event.

## LightEvent_TryWait()

int LightEvent_TryWait | ( | LightEvent * | event | ) |

Attempts to wait on a light event.

Parameters

  event | Pointer to the event.

Returns
  Non-zero if the event was signaled, zero otherwise.

## LightEvent_Wait()

void LightEvent_Wait | ( | LightEvent * | event | ) |

Waits on a light event.

Parameters

  event | Pointer to the event.

## LightEvent_WaitTimeout()

int LightEvent_WaitTimeout | ( | LightEvent * | event,
|  | s64 | timeout_ns
| ) |  |

Waits on a light event until either the event is signaled or the timeout is reached.

Parameters

  event | Pointer to the event.
  timeout_ns | Timeout in nanoseconds.

Returns
  Non-zero on timeout, zero otherwise.

## LightLock_Init()

void LightLock_Init | ( | LightLock * | lock | ) |

Initializes a light lock.

Parameters

  lock | Pointer to the lock.

## LightLock_Lock()

void LightLock_Lock | ( | LightLock * | lock | ) |

Locks a light lock.

Parameters

  lock | Pointer to the lock.

## LightLock_TryLock()

int LightLock_TryLock | ( | LightLock * | lock | ) |

Attempts to lock a light lock.

Parameters

  lock | Pointer to the lock.

Returns
  Zero on success, non-zero on failure.

## LightLock_Unlock()

void LightLock_Unlock | ( | LightLock * | lock | ) |

Unlocks a light lock.

Parameters

  lock | Pointer to the lock.

## LightSemaphore_Acquire()

void LightSemaphore_Acquire | ( | LightSemaphore * | semaphore,
|  | s32 | count
| ) |  |

Acquires a light semaphore.

Parameters

  semaphore | Pointer to the semaphore.
  count | Acquire count

## LightSemaphore_Init()

void LightSemaphore_Init | ( | LightSemaphore * | semaphore,
|  | s16 | initial_count,
|  | s16 | max_count
| ) |  |

Initializes a light semaphore.

Parameters

  event | Pointer to the semaphore.
  max_count | Initial count of the semaphore.
  max_count | Maximum count of the semaphore.

## LightSemaphore_Release()

void LightSemaphore_Release | ( | LightSemaphore * | semaphore,
|  | s32 | count
| ) |  |

Releases a light semaphore.

Parameters

  semaphore | Pointer to the semaphore.
  count | Release count

## LightSemaphore_TryAcquire()

int LightSemaphore_TryAcquire | ( | LightSemaphore * | semaphore,
|  | s32 | count
| ) |  |

Attempts to acquire a light semaphore.

Parameters

  semaphore | Pointer to the semaphore.
  count | Acquire count

Returns
  Zero on success, non-zero on failure

## RecursiveLock_Init()

void RecursiveLock_Init | ( | RecursiveLock * | lock | ) |

Initializes a recursive lock.

Parameters

  lock | Pointer to the lock.

## RecursiveLock_Lock()

void RecursiveLock_Lock | ( | RecursiveLock * | lock | ) |

Locks a recursive lock.

Parameters

  lock | Pointer to the lock.

## RecursiveLock_TryLock()

int RecursiveLock_TryLock | ( | RecursiveLock * | lock | ) |

Attempts to lock a recursive lock.

Parameters

  lock | Pointer to the lock.

Returns
  Zero on success, non-zero on failure.

## RecursiveLock_Unlock()

void RecursiveLock_Unlock | ( | RecursiveLock * | lock | ) |

Unlocks a recursive lock.

Parameters

  lock | Pointer to the lock.

## syncArbitrateAddress()

Result syncArbitrateAddress | ( | s32 * | addr,
|  | ArbitrationType | type,
|  | s32 | value
| ) |  |

Function used to implement user-mode synchronization primitives.

Parameters

  addr | Pointer to a signed 32-bit value whose address will be used to identify waiting threads.
  type | Type of action to be performed by the arbiter
  value | Number of threads to signal if using ARBITRATION_SIGNAL, or the value used for comparison.

This will perform an arbitration based on #type. The comparisons are done between #value and the value at the address #addr.

s32 val=0;
// Does *nothing* since val >= 0
syncArbitrateAddress(&val,ARBITRATION_WAIT_IF_LESS_THAN,0);
ARBITRATION_WAIT_IF_LESS_THAN
@ ARBITRATION_WAIT_IF_LESS_THAN
If the memory at the address is strictly lower than #value, then wait for signal.
Definition: svc.h:90
syncArbitrateAddress
Result syncArbitrateAddress(s32 *addr, ArbitrationType type, s32 value)
Function used to implement user-mode synchronization primitives.
s32
int32_t s32
32-bit signed integer
Definition: types.h:28

Note
  Usage of this function entails an implicit Data Memory Barrier (dmb).

## syncArbitrateAddressWithTimeout()

Result syncArbitrateAddressWithTimeout | ( | s32 * | addr,
|  | ArbitrationType | type,
|  | s32 | value,
|  | s64 | timeout_ns
| ) |  |

Function used to implement user-mode synchronization primitives (with timeout).

Parameters

  addr | Pointer to a signed 32-bit value whose address will be used to identify waiting threads.
  type | Type of action to be performed by the arbiter (must use ARBITRATION_WAIT_IF_LESS_THAN_TIMEOUT or ARBITRATION_DECREMENT_AND_WAIT_IF_LESS_THAN_TIMEOUT)
  value | Number of threads to signal if using ARBITRATION_SIGNAL, or the value used for comparison.

This will perform an arbitration based on #type. The comparisons are done between #value and the value at the address #addr.

s32 val=0;
// Thread will wait for a signal or wake up after 10000000 nanoseconds because val < 1.
syncArbitrateAddressWithTimeout(&val,ARBITRATION_WAIT_IF_LESS_THAN_TIMEOUT,1,10000000LL);
ARBITRATION_WAIT_IF_LESS_THAN_TIMEOUT
@ ARBITRATION_WAIT_IF_LESS_THAN_TIMEOUT
If the memory at the address is strictly lower than #value, then wait for signal or timeout.
Definition: svc.h:92
syncArbitrateAddressWithTimeout
Result syncArbitrateAddressWithTimeout(s32 *addr, ArbitrationType type, s32 value, s64 timeout_ns)
Function used to implement user-mode synchronization primitives (with timeout).

Note
  Usage of this function entails an implicit Data Memory Barrier (dmb).