libnx  v4.2.0
thread.h
Go to the documentation of this file.
1 /**
2  * @file thread.h
3  * @brief Multi-threading support
4  * @author plutoo
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../arm/thread_context.h"
10 #include "wait.h"
11 
12 /// Thread information structure.
13 typedef struct Thread {
14  Handle handle; ///< Thread handle.
15  bool owns_stack_mem; ///< Whether the stack memory is automatically allocated.
16  void* stack_mem; ///< Pointer to stack memory.
17  void* stack_mirror; ///< Pointer to stack memory mirror.
18  size_t stack_sz; ///< Stack size.
19  void** tls_array;
20  struct Thread* next;
21  struct Thread** prev_next;
22 } Thread;
23 
24 /// Creates a \ref Waiter for a \ref Thread.
25 static inline Waiter waiterForThread(Thread* t)
26 {
27  return waiterForHandle(t->handle);
28 }
29 
30 /**
31  * @brief Creates a thread.
32  * @param t Thread information structure which will be filled in.
33  * @param entry Entrypoint of the thread.
34  * @param arg Argument to pass to the entrypoint.
35  * @param stack_mem Memory to use as backing for stack/tls/reent. Must be page-aligned. NULL argument means to allocate new memory.
36  * @param stack_sz If stack_mem is NULL, size to use for stack. If stack_mem is non-NULL, size to use for stack + reent + tls (must be page-aligned).
37  * @param prio Thread priority (0x00~0x3F); 0x2C is the usual priority of the main thread, 0x3B is a special priority on cores 0..2 that enables preemptive multithreading (0x3F on core 3).
38  * @param cpuid ID of the core on which to create the thread (0~3); or -2 to use the default core for the current process.
39  * @return Result code.
40  */
42  Thread* t, ThreadFunc entry, void* arg, void *stack_mem, size_t stack_sz,
43  int prio, int cpuid);
44 
45 /**
46  * @brief Starts the execution of a thread.
47  * @param t Thread information structure.
48  * @return Result code.
49  */
51 
52 /**
53  * @brief Exits the current thread immediately.
54  */
55 void NORETURN threadExit(void);
56 
57 /**
58  * @brief Waits for a thread to finish executing.
59  * @param t Thread information structure.
60  * @return Result code.
61  */
63 
64 /**
65  * @brief Frees up resources associated with a thread.
66  * @param t Thread information structure.
67  * @return Result code.
68  */
70 
71 /**
72  * @brief Pauses the execution of a thread.
73  * @param t Thread information structure.
74  * @return Result code.
75  */
77 
78 /**
79  * @brief Resumes the execution of a thread, after having been paused.
80  * @param t Thread information structure.
81  * @return Result code.
82  */
84 
85 /**
86  * @brief Dumps the registers of a thread paused by @ref threadPause (register groups: all).
87  * @param[out] ctx Output thread context (register dump).
88  * @param t Thread information structure.
89  * @return Result code.
90  * @warning Official kernel will not dump x0..x18 if the thread is currently executing a system call, and prior to 6.0.0 doesn't dump TPIDR_EL0.
91  */
93 
94 /**
95  * @brief Gets a pointer to the current thread structure.
96  * @return Thread information structure.
97  */
98 Thread *threadGetSelf(void);
99 
100 /**
101  * @brief Gets the raw handle to the current thread.
102  * @return The current thread's handle.
103  */
105 
106 /**
107  * @brief Allocates a TLS slot.
108  * @param destructor Function to run automatically when a thread exits.
109  * @return TLS slot ID on success, or a negative value on failure.
110  */
111 s32 threadTlsAlloc(void (* destructor)(void*));
112 
113 /**
114  * @brief Retrieves the value stored in a TLS slot.
115  * @param slot_id TLS slot ID.
116  * @return Value.
117  */
118 void* threadTlsGet(s32 slot_id);
119 
120 /**
121  * @brief Stores the specified value into a TLS slot.
122  * @param slot_id TLS slot ID.
123  * @param value Value.
124  */
125 void threadTlsSet(s32 slot_id, void* value);
126 
127 /**
128  * @brief Frees a TLS slot.
129  * @param slot_id TLS slot ID.
130  */
131 void threadTlsFree(s32 slot_id);
Thread::owns_stack_mem
bool owns_stack_mem
Whether the stack memory is automatically allocated.
Definition: thread.h:15
threadTlsFree
void threadTlsFree(s32 slot_id)
Frees a TLS slot.
waiterForThread
static Waiter waiterForThread(Thread *t)
Creates a Waiter for a Thread.
Definition: thread.h:25
threadPause
Result threadPause(Thread *t)
Pauses the execution of a thread.
Thread::stack_sz
size_t stack_sz
Stack size.
Definition: thread.h:18
Thread::stack_mem
void * stack_mem
Pointer to stack memory.
Definition: thread.h:16
ThreadFunc
void(* ThreadFunc)(void *)
Thread entrypoint function.
Definition: types.h:45
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
threadResume
Result threadResume(Thread *t)
Resumes the execution of a thread, after having been paused.
Thread::handle
Handle handle
Thread handle.
Definition: thread.h:14
wait.h
User mode synchronization primitive waiting operations.
threadClose
Result threadClose(Thread *t)
Frees up resources associated with a thread.
threadGetCurHandle
Handle threadGetCurHandle(void)
Gets the raw handle to the current thread.
Waiter
Waiter structure, representing any generic waitable synchronization object; both kernel-mode and user...
Definition: wait.h:36
threadExit
void threadExit(void)
Exits the current thread immediately.
threadTlsSet
void threadTlsSet(s32 slot_id, void *value)
Stores the specified value into a TLS slot.
Thread::stack_mirror
void * stack_mirror
Pointer to stack memory mirror.
Definition: thread.h:17
threadTlsGet
void * threadTlsGet(s32 slot_id)
Retrieves the value stored in a TLS slot.
Result
u32 Result
Function error code result type.
Definition: types.h:44
waiterForHandle
static Waiter waiterForHandle(Handle h)
Creates a Waiter for a kernel-mode Handle.
Definition: wait.h:46
Thread
Thread information structure.
Definition: thread.h:13
threadDumpContext
Result threadDumpContext(ThreadContext *ctx, Thread *t)
Dumps the registers of a thread paused by threadPause (register groups: all).
threadTlsAlloc
s32 threadTlsAlloc(void(*destructor)(void *))
Allocates a TLS slot.
ThreadContext
Thread context structure (register dump)
Definition: thread_context.h:49
threadGetSelf
Thread * threadGetSelf(void)
Gets a pointer to the current thread structure.
NORETURN
#define NORETURN
Marks a function as not returning, for the purposes of compiler optimization.
Definition: types.h:64
threadCreate
Result threadCreate(Thread *t, ThreadFunc entry, void *arg, void *stack_mem, size_t stack_sz, int prio, int cpuid)
Creates a thread.
Handle
u32 Handle
Kernel object handle.
Definition: types.h:43
threadStart
Result threadStart(Thread *t)
Starts the execution of a thread.
threadWaitForExit
Result threadWaitForExit(Thread *t)
Waits for a thread to finish executing.