Thread Management

Overview

The thread API provides functions for creating and managing PPU threads, along with synchronization primitives like mutexes and condition variables.

Thread Management

sysThreadCreate

Create a new PPU thread.

s32 sysThreadCreate(sys_ppu_thread_t *threadid,
                    void (*entry)(void *),
                    void *arg,
                    s32 priority,
                    u64 stacksize,
                    u64 flags,
                    char *threadname);

threadid

sys_ppu_thread_t*

required

Pointer to storage for the thread ID

entry

void (*)(void*)

required

Thread entry point function

arg

void*

Argument passed to entry function

priority

s32

required

Thread priority (0 = highest, higher values = lower priority)

stacksize

u64

required

Stack size in bytes

flags

u64

required

Thread flags: THREAD_JOINABLE (1) or 0

threadname

char*

Thread name for debugging

return

s32

Zero on success, error code otherwise

Example:

void thread_func(void *arg) {
    printf("Thread running: %s\n", (char*)arg);
    sysThreadExit(0);
}

int main() {
    sys_ppu_thread_t thread;
    s32 ret = sysThreadCreate(&thread, thread_func, "Hello",
                              1000, 0x1000, THREAD_JOINABLE,
                              "MyThread");
    if (ret == 0) {
        u64 retval;
        sysThreadJoin(thread, &retval);
    }
    return 0;
}

sysThreadJoin

Wait for a joinable thread to terminate.

s32 sysThreadJoin(sys_ppu_thread_t threadid, u64 *retval);

threadid

sys_ppu_thread_t

required

Thread ID returned by sysThreadCreate

retval

u64*

Pointer to storage for thread return value

return

s32

Zero on success, error code otherwise

sysThreadExit

Terminate the current thread.

void sysThreadExit(u64 ret_val);

ret_val

u64

required

Return value for sysThreadJoin

sysThreadYield

Voluntarily yield the CPU to another thread.

s32 sysThreadYield(void);

return

s32

Zero on success, error code otherwise

sysThreadDetach

Make a thread non-joinable (detached).

s32 sysThreadDetach(sys_ppu_thread_t threadid);

threadid

sys_ppu_thread_t

required

Thread ID to detach

return

s32

Zero on success, error code otherwise

sysThreadGetId

Get the current thread’s ID.

s32 sysThreadGetId(sys_ppu_thread_t *threadid);

threadid

sys_ppu_thread_t*

required

Pointer to storage for current thread ID

return

s32

Zero on success, error code otherwise

sysThreadSetPriority

Change thread priority.

s32 sysThreadSetPriority(sys_ppu_thread_t threadid, s32 prio);

threadid

sys_ppu_thread_t

required

Thread ID

prio

s32

required

New priority value

return

s32

Zero on success, error code otherwise

sysThreadGetPriority

Get thread priority.

s32 sysThreadGetPriority(sys_ppu_thread_t threadid, s32 *prio);

threadid

sys_ppu_thread_t

required

Thread ID

prio

s32*

required

Pointer to storage for priority value

return

s32

Zero on success, error code otherwise

Mutex

sysMutexCreate

Create a mutex for mutual exclusion.

s32 sysMutexCreate(sys_mutex_t *mutex, const sys_mutex_attr_t *attr);

mutex

sys_mutex_t*

required

Pointer to storage for mutex ID

attr

const sys_mutex_attr_t*

required

Pointer to mutex attributes

return

s32

Zero on success, error code otherwise

Example:

sys_mutex_t mutex;
sys_mutex_attr_t attr;
sysMutexAttrInitialize(attr);
attr.attr_protocol = SYS_MUTEX_PROTOCOL_PRIO;
attr.attr_recursive = SYS_MUTEX_ATTR_NOT_RECURSIVE;

s32 ret = sysMutexCreate(&mutex, &attr);
if (ret == 0) {
    sysMutexLock(mutex, 0);
    // Critical section
    sysMutexUnlock(mutex);
    sysMutexDestroy(mutex);
}

sysMutexDestroy

Destroy a mutex.

s32 sysMutexDestroy(sys_mutex_t mutex);

mutex

sys_mutex_t

required

Mutex ID

return

s32

Zero on success, error code otherwise

sysMutexLock

Lock a mutex (blocking).

s32 sysMutexLock(sys_mutex_t mutex, u64 timeout_usec);

mutex

sys_mutex_t

required

Mutex ID

timeout_usec

u64

Timeout in microseconds, or 0 for no timeout

return

s32

Zero on success, error code on timeout or error

sysMutexTryLock

Attempt to lock a mutex without blocking.

s32 sysMutexTryLock(sys_mutex_t mutex);

mutex

sys_mutex_t

required

Mutex ID

return

s32

Zero if locked successfully, nonzero if already locked or error

sysMutexUnlock

Unlock a previously locked mutex.

s32 sysMutexUnlock(sys_mutex_t mutex);

mutex

sys_mutex_t

required

Mutex ID

return

s32

Zero on success, error code otherwise

Condition Variables

sysCondCreate

Create a condition variable.

s32 sysCondCreate(sys_cond_t *cond,
                  sys_mutex_t mutex,
                  const sys_cond_attr_t *attr);

cond

sys_cond_t*

required

Pointer to storage for condition variable ID

mutex

sys_mutex_t

required

Associated mutex ID

attr

const sys_cond_attr_t*

required

Pointer to condition variable attributes

return

s32

Zero on success, error code otherwise

Example:

sys_mutex_t mutex;
sys_cond_t cond;
sys_mutex_attr_t mutex_attr;
sys_cond_attr_t cond_attr;

sysMutexAttrInitialize(mutex_attr);
sysCondAttrInitialize(cond_attr);

sysMutexCreate(&mutex, &mutex_attr);
sysCondCreate(&cond, mutex, &cond_attr);

// Wait for condition
sysMutexLock(mutex, 0);
while (!condition_met) {
    sysCondWait(cond, 0);
}
sysMutexUnlock(mutex);

// Signal condition
sysMutexLock(mutex, 0);
condition_met = true;
sysCondSignal(cond);
sysMutexUnlock(mutex);

sysCondDestroy

Destroy a condition variable.

s32 sysCondDestroy(sys_cond_t cond);

cond

sys_cond_t

required

Condition variable ID

return

s32

Zero on success, error code otherwise

sysCondWait

Wait for a condition variable to be signaled.

s32 sysCondWait(sys_cond_t cond, u64 timeout_usec);

cond

sys_cond_t

required

Condition variable ID

timeout_usec

u64

Timeout in microseconds, or 0 for no timeout

return

s32

Zero on success, error code on timeout or error

sysCondSignal

Signal one waiting thread.

s32 sysCondSignal(sys_cond_t cond);

cond

sys_cond_t

required

Condition variable ID

return

s32

Zero on success, error code otherwise

sysCondBroadcast

Signal all waiting threads.

s32 sysCondBroadcast(sys_cond_t cond);

cond

sys_cond_t

required

Condition variable ID

return

s32

Zero on success, error code otherwise

Constants

Thread Flags

THREAD_JOINABLE (1) - Thread can be joined
THREAD_INTERRUPT (2) - Thread triggered by interrupt

Mutex Protocols

SYS_MUTEX_PROTOCOL_FIFO (1) - FIFO scheduling
SYS_MUTEX_PROTOCOL_PRIO (2) - Priority-based scheduling
SYS_MUTEX_PROTOCOL_PRIO_INHERIT (3) - Priority inheritance

Mutex Attributes

SYS_MUTEX_ATTR_RECURSIVE (0x0010) - Allow recursive locking
SYS_MUTEX_ATTR_NOT_RECURSIVE (0x0020) - Disallow recursive locking
SYS_MUTEX_ATTR_ADAPTIVE (0x1000) - Adaptive mutex
SYS_MUTEX_ATTR_NOT_ADAPTIVE (0x2000) - Non-adaptive mutex

Header Files

#include <sys/thread.h>  // Thread functions
#include <sys/mutex.h>   // Mutex functions
#include <sys/cond.h>    // Condition variable functions
#include <lv2/thread.h>  // Additional thread utilities

Graphics APIs

Input APIs

Audio APIs

Network APIs

System APIs

System Utility APIs

Media APIs

Device APIs

SPU APIs

Math Libraries

Thread Management

Overview