Provides functions to use threads. More...

#include <3ds/types.h>
#include <3ds/result.h>
#include <3ds/synchronization.h>
#include <3ds/svc.h>
#include <3ds/errf.h>

Macros
#define	RUN_HANDLER_ON_FAULTING_STACK ((void*)1)
	Makes the exception handler reuse the stack of the faulting thread as-is.

#define	WRITE_DATA_TO_HANDLER_STACK NULL
	Makes the exception handler push the exception data on its stack.

#define	WRITE_DATA_TO_FAULTING_STACK ((ERRF_ExceptionData*)1)
	Makes the exception handler push the exception data on the stack of the faulting thread.

Typedefs
typedef struct Thread_tag *	Thread
	libctru thread handle type

typedef void(*	ExceptionHandler) (ERRF_ExceptionInfo excep, CpuRegisters regs)
	Exception handler type, necessarily an ARM function that does not return.

Functions
Thread	threadCreate (ThreadFunc entrypoint, void *arg, size_t stack_size, int prio, int core_id, bool detached)
	Creates a new libctru thread. More...

Handle	threadGetHandle (Thread thread)
	Retrieves the OS thread handle of a libctru thread. More...

int	threadGetExitCode (Thread thread)
	Retrieves the exit code of a finished libctru thread. More...

void	threadFree (Thread thread)
	Frees a finished libctru thread. More...

Result	threadJoin (Thread thread, u64 timeout_ns)
	Waits for a libctru thread to finish (or returns immediately if it is already finished). More...

void	threadDetach (Thread thread)
	Changes a thread's status from attached to detached. More...

Thread	threadGetCurrent (void)
	Retrieves the libctru thread handle of the current thread. More...

void	threadExit (int rc) __attribute__((noreturn))
	Exits the current libctru thread with an exit code (not usable from the main thread). More...

static void	threadOnException (ExceptionHandler handler, void stack_top, ERRF_ExceptionData exception_data)
	Sets the exception handler for the current thread. More...

Detailed Description

Provides functions to use threads.

Function Documentation

◆ threadCreate()

Thread threadCreate	(	ThreadFunc	entrypoint,
		void *	arg,
		size_t	stack_size,
		int	prio,
		int	core_id,
		bool	detached
	)

Creates a new libctru thread.

Parameters

entrypoint	The function that will be called first upon thread creation
arg	The argument passed to `entrypoint`
stack_size	The size of the stack that will be allocated for the thread (will be rounded to a multiple of 8 bytes)
prio	Low values gives the thread higher priority. For userland apps, this has to be within the range [0x18;0x3F]. The main thread usually has a priority of 0x30, but not always. Use svcGetThreadPriority() if you need to create a thread with a priority that is explicitly greater or smaller than that of the main thread.
core_id	The ID of the processor the thread should be ran on. Processor IDs are labeled starting from 0. On Old3DS it must be <2, and on New3DS it must be <4. Pass -1 to execute the thread on all CPUs and -2 to execute the thread on the default CPU (read from the Exheader).
detached	When set to true, the thread is automatically freed when it finishes.

Returns: The libctru thread handle on success, NULL on failure.

Processor #0 is the application core. It is always possible to create a thread on this core.
Processor #1 is the system core. If APT_SetAppCpuTimeLimit is used, it is possible to create a single thread on this core.
Processor #2 is New3DS exclusive. Normal applications can create threads on this core if the exheader kernel flags bitmask has 0x2000 set.
Processor #3 is New3DS exclusive. Normal applications cannot create threads on this core.
Processes in the BASE memory region can always create threads on processors #2 and #3.

Note: Default exit code of a thread is 0.

Warning: svcExitThread should never be called from the thread, use threadExit instead.

Examples: threads/event/source/main.c, and threads/thread-basic/source/main.c.

◆ threadDetach()

void threadDetach ( Thread thread )

Changes a thread's status from attached to detached.

Parameters

thread libctru thread handle

◆ threadExit()

void threadExit ( int rc )

Exits the current libctru thread with an exit code (not usable from the main thread).

Parameters

rc Exit code

◆ threadFree()

void threadFree ( Thread thread )

Frees a finished libctru thread.

Parameters

thread libctru thread handle

Remarks: This function should not be called if the thread is detached, as it is freed automatically when it finishes.

Examples: threads/thread-basic/source/main.c.

◆ threadGetCurrent()

Thread threadGetCurrent ( void )

Retrieves the libctru thread handle of the current thread.

Returns: libctru thread handle of the current thread, or NULL for the main thread

◆ threadGetExitCode()

int threadGetExitCode ( Thread thread )

Retrieves the exit code of a finished libctru thread.

Parameters

thread libctru thread handle

Returns: Exit code

◆ threadGetHandle()

Handle threadGetHandle ( Thread thread )

Retrieves the OS thread handle of a libctru thread.

Parameters

thread libctru thread handle

Returns: OS thread handle

◆ threadJoin()

Result threadJoin	(	Thread	thread,
		u64	timeout_ns
	)

Waits for a libctru thread to finish (or returns immediately if it is already finished).

Parameters

thread	libctru thread handle
timeout_ns	Timeout in nanoseconds. Pass U64_MAX if a timeout isn't desired

Examples: threads/event/source/main.c, and threads/thread-basic/source/main.c.

◆ threadOnException()

static void threadOnException	(	ExceptionHandler	handler,
		void *	stack_top,
		ERRF_ExceptionData *	exception_data
	)

inlinestatic

Sets the exception handler for the current thread.

Called from the main thread, this sets the default handler.

Parameters

handler	The exception handler, necessarily an ARM function that does not return
stack_top	A pointer to the top of the stack that will be used by the handler. See also RUN_HANDLER_ON_FAULTING_STACK
exception_data	A pointer to the buffer that will contain the exception data. See also WRITE_DATA_TO_HANDLER_STACK and WRITE_DATA_TO_FAULTING_STACK

To have CPU exceptions reported through this mechanism, it is normally necessary that UNITINFO is set to a non-zero value when Kernel11 starts, and this mechanism is also controlled by svcKernelSetState type 6, see 3dbrew.

VFP exceptions are always reported this way even if the process is being debugged using the debug SVCs.

The current thread need not be a libctru thread.

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ threadCreate()

◆ threadDetach()

◆ threadExit()

◆ threadFree()

◆ threadGetCurrent()

◆ threadGetExitCode()

◆ threadGetHandle()

◆ threadJoin()

◆ threadOnException()