thread.h File Reference

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>`

Go to the source code of this file.

## 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.