KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
thread.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 include/kos/thread.h
4 Copyright (C) 2000, 2001, 2002, 2003 Megan Potter
5 Copyright (C) 2009, 2010, 2016 Lawrence Sebald
6 Copyright (C) 2023 Colton Pawielski
7 Copyright (C) 2023, 2024 Falco Girgis
8
9*/
10
11/** \file kos/thread.h
12 \brief Threading support.
13 \ingroup kthreads
14
15 This file contains the interface to the threading system of KOS. Timer
16 interrupts are used to reschedule threads within the system.
17
18 \see arch/timer.h
19 \see kos/genwait.h
20 \see kos/mutex.h
21 \see kos/once.h
22 \see kos/recursive_lock.h
23 \see kos/rwsem.h
24 \see kos/sem.h
25 \see kos/tls.h
26
27 \todo
28 - Remove deprecated thread mode API
29 - Remove global extern pointer to current thread
30
31 \author Megan Potter
32 \author Lawrence Sebald
33 \author Falco Girgis
34*/
35
36#ifndef __KOS_THREAD_H
37#define __KOS_THREAD_H
38
39#include <sys/cdefs.h>
40__BEGIN_DECLS
41
42#include <kos/cdefs.h>
43#include <kos/tls.h>
44#include <arch/irq.h>
45#include <sys/queue.h>
46#include <sys/reent.h>
47
48#include <stdint.h>
49#include <stdbool.h>
50
51/** \defgroup kthreads Kernel
52 \brief KOS Native Kernel Threading API
53 \ingroup threading
54
55 The thread scheduler itself is a relatively simplistic priority scheduler.
56 There is no provision for priorities to erode over time, so keep that in
57 mind. That practically means that if you have 2 high priority threads that
58 are always runnable and one low priority thread that is always runnable, the
59 low priority thread will never actually run (since it will never get to the
60 front of the run queue because of the high priority threads).
61
62 The scheduler supports two distinct types of threads: joinable and detached
63 threads. A joinable thread is one that can return a value to the creating
64 thread (or for that matter, any other thread that wishes to join it). A
65 detached thread is one that is completely detached from the rest of the
66 system and cannot return values by "normal" means. Detached threads
67 automatically clean up all of the internal resources associated with the
68 thread when it exits. Joinable threads, on the other hand, must keep some
69 state available for the ability to return values. To make sure that all
70 memory allocated by the thread's internal structures gets freed, you must
71 either join with the thread (with thd_join()) or detach it (with
72 thd_detach()). The old KOS threading system only had what would be
73 considered detached threads.
74
75 \sa semaphore_t, mutex_t, kthread_once_t, kthread_key_t, rw_semaphore_t
76
77 @{
78*/
79
80/** \brief Process ID
81
82 This macro defines the single process ID that encompasses all of KOS and the
83 running application along with all of its threads.
84*/
85#define KOS_PID 1
86
87/** \brief Maximal thread priority
88
89 This macro defines the maximum value for a thread's priority. Note that the
90 larger this number, the lower the priority of the thread.
91*/
92#define PRIO_MAX 4096
93
94/** \brief Default thread priority
95
96 Threads are created by default with the priority specified.
97*/
98#define PRIO_DEFAULT 10
99
100/** \brief Size of a kthread's label
101
102 Maximum number of characters in a thread's label or name
103 (including NULL terminator).
104*/
105#define KTHREAD_LABEL_SIZE 256
106
107/** \brief Size of a kthread's current directory
108
109 Maximum number of characters in a thread's current working
110 directory (including NULL terminator).
111*/
112#define KTHREAD_PWD_SIZE 256
113
114/* Pre-define list/queue types */
115struct kthread;
116
117/* \cond */
118TAILQ_HEAD(ktqueue, kthread);
119LIST_HEAD(ktlist, kthread);
120/* \endcond */
121
122/** \name Thread flag values
123 \brief Flags for kthread_flags_t
124
125 These are possible values for the flags field on the kthread_t structure.
126 These can be ORed together.
127
128 @{
129*/
130#define THD_DEFAULTS 0 /**< \brief Defaults: no flags */
131#define THD_USER 1 /**< \brief Thread runs in user mode */
132#define THD_QUEUED 2 /**< \brief Thread is in the run queue */
133#define THD_DETACHED 4 /**< \brief Thread is detached */
134#define THD_OWNS_STACK 8 /**< \brief Thread manages stack lifetime */
135/** @} */
136
137/** \brief Kernel thread flags type */
138typedef uint8_t kthread_flags_t;
139
140/** \brief Kernel thread state
141
142 Each thread in the system is in exactly one of this set of states.
143*/
144typedef enum kthread_state {
145 STATE_ZOMBIE = 0x0000, /**< \brief Waiting to die */
146 STATE_RUNNING = 0x0001, /**< \brief Process is "current" */
147 STATE_READY = 0x0002, /**< \brief Ready to be scheduled */
148 STATE_WAIT = 0x0003, /**< \brief Blocked on a genwait */
149 STATE_FINISHED = 0x0004 /**< \brief Finished execution */
151
152
153
154/** \brief Structure describing one running thread.
155
156 Each thread has one of these structures assigned to it, which holds all the
157 data associated with the thread. There are various functions to manipulate
158 the data in here, so you shouldn't generally do so manually.
159*/
160typedef __attribute__((aligned(32))) struct kthread {
161 /** \brief Register store -- used to save thread context. */
163
164 /** \brief Thread list handle. Not a function. */
165 LIST_ENTRY(kthread) t_list;
166
167 /** \brief Run/Wait queue handle. Once again, not a function. */
168 TAILQ_ENTRY(kthread) thdq;
169
170 /** \brief Timer queue handle (if applicable). Also not a function. */
171 TAILQ_ENTRY(kthread) timerq;
172
173 /** \brief Kernel thread id. */
175
176 /** \brief Dynamic priority */
178
179 /** \brief Static priority: 0..PRIO_MAX (higher means lower priority). */
181
182 /** \brief Thread flags. */
184
185 /** \brief Process state */
187
188 /** \brief Generic wait target, if waiting.
189
190 \see kos/genwait.h
191 */
192 void *wait_obj;
193
194 /** \brief Generic wait message, if waiting.
195
196 \see kos/genwait.h
197 */
198 const char *wait_msg;
199
200 /** \brief Wait timeout callback.
201
202 If the genwait times out while waiting, this function will be called.
203 This allows hooks for things like fixing up semaphore count values, etc.
204
205 \param obj The object that we were waiting on.
206 */
207 void (*wait_callback)(void *obj);
208
209 /** \brief Next scheduled time.
210
211 This value is used for sleep and timed block operations. This value is
212 in milliseconds since the start of timer_ms_gettime(). This should be
213 enough for something like 2 million years of wait time. ;)
214 */
215 uint64_t wait_timeout;
216
217 /** \brief Per-Thread CPU Time. */
218 struct {
219 uint64_t scheduled; /**< \brief time when the thread became active */
220 uint64_t total; /**< \brief total running CPU time for thread */
221 } cpu_time;
222
223 /** \brief Thread label.
224
225 This value is used when printing out a user-readable process listing.
226 */
228
229 /** \brief Current file system path. */
231
232 /** \brief Thread private stack.
233
234 This should be a pointer to the base of a stack page.
235 */
236 void *stack;
237
238 /** \brief Size of the thread's stack, in bytes. */
240
241 /** \brief Thread errno variable. */
243
244 /** \brief Our reent struct for newlib. */
245 struct _reent thd_reent;
246
247 /** \brief OS-level thread-local storage.
248
249 \see kos/tls.h
250 */
251 struct kthread_tls_kv_list tls_list;
252
253 /** \brief Compiler-level thread-local storage. */
254 void *tls_hnd;
255
256 /** \brief Return value of the thread function.
257
258 This is only used in joinable threads.
259 */
260 void *rv;
261} kthread_t;
262
263/** \brief Thread creation attributes.
264
265 This structure allows you to specify the various attributes for a thread to
266 have when it is created. These can only be modified (in general) at thread
267 creation time (with the exception of detaching a thread, which can be done
268 later with thd_detach()).
269
270 Leaving any of the attributes in this structure 0 will set them to their
271 default value.
272
273 \headerfile kos/thread.h
274*/
275typedef struct kthread_attr {
276 /** \brief 1 for a detached thread. */
278
279 /** \brief Set the size of the stack to be created. */
281
282 /** \brief Pre-allocate a stack for the thread.
283 \note If you use this attribute, you must also set stack_size. */
285
286 /** \brief Set the thread's priority. */
288
289 /** \brief Thread label. */
290 const char *label;
292
293/** \brief kthread mode values
294
295 \deprecated
296 Only preemptive scheduling is still supported!
297
298 The threading system will always be in one of the following modes. This
299 represents either pre-emptive scheduling or an un-initialized state.
300*/
301typedef enum kthread_mode {
302 THD_MODE_NONE = -1, /**< \brief Threads not running */
303 THD_MODE_COOP = 0, /**< \brief Cooperative mode \deprecated */
304 THD_MODE_PREEMPT = 1 /**< \brief Preemptive threading mode */
306
307/** \cond The currently executing thread -- Do not manipulate directly! */
308extern kthread_t *thd_current;
309/** \endcond */
310
311/** \brief Block the current thread.
312
313 Blocks the calling thread and performs a reschedule as if a context switch
314 timer had been executed. This is useful for, e.g., blocking on sync
315 primitives. The param 'mycxt' should point to the calling thread's context
316 block. This is implemented in arch-specific code.
317
318 The meaningfulness of the return value depends on whether the unblocker set
319 a return value or not.
320
321 \param mycxt The IRQ context of the calling thread.
322
323 \return Whatever the unblocker deems necessary to return.
324*/
326
327/** \brief Find a new thread to swap in.
328
329 This function looks at the state of the system and returns a new thread
330 context to swap in. This is called from thd_block_now() and from the
331 preemptive context switcher. Note that thd_current might be NULL on entering
332 this function, if the caller blocked itself.
333
334 It is assumed that by the time this returns, the irq_srt_addr and
335 thd_current will be updated.
336
337 \return The IRQ context of the thread selected.
338*/
340
341/** \brief Given a thread ID, locates the thread structure.
342 \relatesalso kthread_t
343
344 \param tid The thread ID to retrieve.
345
346 \return The thread on success, NULL on failure.
347*/
349
350/** \brief Enqueue a process in the runnable queue.
351 \relatesalso kthread_t
352
353 This function adds a thread to the runnable queue after the process group of
354 the same priority if front_of_line is zero, otherwise queues it at the front
355 of its priority group. Generally, you will not have to do this manually.
356
357 \param t The thread to queue.
358 \param front_of_line Set to true to put this thread in front of other
359 threads of the same priority, false to put it
360 behind the other threads (normal behavior).
361
362 \sa thd_remove_from_runnable
363*/
364void thd_add_to_runnable(kthread_t *t, bool front_of_line);
365
366/** \brief Removes a thread from the runnable queue, if it's there.
367 \relatesalso kthread_t
368
369 This function removes a thread from the runnable queue, if it is currently
370 in that queue. Generally, you shouldn't have to do this manually, as waiting
371 on synchronization primitives and the like will do this for you if needed.
372
373 \param thd The thread to remove from the runnable queue.
374
375 \retval 0 On success, or if the thread isn't runnable.
376
377 \sa thd_add_to_runnable
378*/
380
381/** \brief Create a new thread.
382 \relatesalso kthread_t
383
384 This function creates a new kernel thread with default parameters to run the
385 given routine. The thread will terminate and clean up resources when the
386 routine completes if the thread is created detached, otherwise you must
387 join the thread with thd_join() to clean up after it.
388
389 \param detach Set to true to create a detached thread. Set to
390 false to create a joinable thread.
391 \param routine The function to call in the new thread.
392 \param param A parameter to pass to the function called.
393
394 \return The new thread on success, NULL on failure.
395
396 \sa thd_create_ex, thd_destroy
397*/
398kthread_t *thd_create(bool detach, void *(*routine)(void *param), void *param);
399
400/** \brief Create a new thread with the specified set of attributes.
401 \relatesalso kthread_t
402
403 This function creates a new kernel thread with the specified set of
404 parameters to run the given routine.
405
406 \param attr A set of thread attributes for the created thread.
407 Passing NULL will initialize all attributes to their
408 default values.
409 \param routine The function to call in the new thread.
410 \param param A parameter to pass to the function called.
411
412 \return The new thread on success, NULL on failure.
413
414 \sa thd_create, thd_destroy
415*/
417 void *(*routine)(void *param), void *param);
418
419/** \brief Brutally kill the given thread.
420 \relatesalso kthread_t
421
422 This function kills the given thread, removing it from the execution chain,
423 cleaning up thread-local data and other internal structures. In general, you
424 shouldn't call this function at all.
425
426 \warning
427 You should never call this function on the current thread.
428
429 \param thd The thread to destroy.
430 \retval 0 On success.
431
432 \sa thd_create
433*/
435
436/** \brief Exit the current thread.
437
438 This function ends the execution of the current thread, removing it from all
439 execution queues. This function will never return to the thread. Returning
440 from the thread's function is equivalent to calling this function.
441
442 \param rv The return value of the thread.
443*/
444void thd_exit(void *rv) __noreturn;
445
446/** \brief Force a thread reschedule.
447
448 This function is the thread scheduler, and is generally called from a timer
449 interrupt. You will most likely never have a reason to call this function
450 directly.
451
452 For most cases, you'll want to set front_of_line to zero, but read the
453 comments in kernel/thread/thread.c for more info, especially if you need to
454 guarantee low latencies. This function just updates irq_srt_addr and
455 thd_current. Set 'now' to non-zero if you want to use a particular system
456 time for checking timeouts.
457
458 \param front_of_line Set to false, unless you have a good reason not to.
459 \param now Set to 0, unless you have a good reason not to.
460
461 \sa thd_schedule_next
462*/
463void thd_schedule(bool front_of_line, uint64_t now);
464
465/** \brief Force a given thread to the front of the queue.
466 \relatesalso kthread_t
467
468 This function promotes the given thread to be the next one that will be
469 swapped in by the scheduler. This function is only callable inside an
470 interrupt context (it simply returns otherwise).
471
472 \param thd The thread to schedule next.
473*/
475
476/** \brief Throw away the current thread's timeslice.
477
478 This function manually yields the current thread's timeslice to the system,
479 forcing a reschedule to occur.
480*/
481void thd_pass(void);
482
483/** \brief Sleep for a given number of milliseconds.
484
485 This function puts the current thread to sleep for the specified amount of
486 time. The thread will be removed from the runnable queue until the given
487 number of milliseconds passes. That is to say that the thread will sleep for
488 at least the given number of milliseconds. If another thread is running, it
489 will likely sleep longer.
490
491 \note
492 When \p ms is given a value of `0`, this is equivalent to thd_pass().
493
494 \param ms The number of milliseconds to sleep.
495*/
496void thd_sleep(unsigned ms);
497
498/** \brief Set a thread's priority value.
499 \relatesalso kthread_t
500
501 This function is used to change the priority value of a thread. If the
502 thread is scheduled already, it will be rescheduled with the new priority
503 value.
504
505 \param thd The thread to change the priority of.
506 \param prio The priority value to assign to the thread.
507
508 \retval 0 On success.
509 \retval -1 thd is NULL.
510 \retval -2 prio requested was out of range.
511*/
513
514/** \brief Retrieve the current thread's kthread struct.
515 \relatesalso kthread_t
516
517 \return The current thread's structure.
518*/
520
521/** \brief Retrieve the thread's label.
522 \relatesalso kthread_t
523
524 \param thd The thread to retrieve from.
525
526 \return The human-readable label of the thread.
527
528 \sa thd_set_label
529*/
530const char *thd_get_label(kthread_t *thd);
531
532/** \brief Set the thread's label.
533 \relatesalso kthread_t
534
535 This function sets the label of a thread, which is simply a human-readable
536 string that is used to identify the thread. These labels aren't used for
537 anything internally, and you can give them any label you want. These are
538 mainly seen in the printouts from thd_pslist() or thd_pslist_queue().
539
540 \param thd The thread to set the label of.
541 \param label The string to set as the label.
542
543 \sa thd_get_label
544*/
545void thd_set_label(kthread_t *thd, const char *__RESTRICT label);
546
547/** \brief Retrieve the thread's current working directory.
548 \relatesalso kthread_t
549
550 This function retrieves the working directory of a thread. Generally, you
551 will want to use either fs_getwd() or one of the standard C functions for
552 doing this, but this is here in case you need it when the thread isn't
553 active for some reason.
554
555 \param thd The thread to retrieve from.
556
557 \return The thread's working directory.
558
559 \sa thd_set_pd
560*/
561const char *thd_get_pwd(kthread_t *thd);
562
563/** \brief Set the thread's current working directory.
564 \relatesalso kthread_t
565
566 This function will set the working directory of a thread. Generally, you
567 will want to use either fs_chdir() or the standard C chdir() function to
568 do this, but this is here in case you need to do it while the thread isn't
569 active for some reason.
570
571 \param thd The thread to set the working directory of.
572 \param pwd The directory to set as active.
573
574 \sa thd_get_pwd
575*/
576void thd_set_pwd(kthread_t *thd, const char *__RESTRICT pwd);
577
578/** \brief Retrieve a pointer to the thread errno.
579 \relatesalso kthread_t
580
581 This function retrieves a pointer to the errno value for the thread. You
582 should generally just use the errno variable to access this.
583
584 \param thd The thread to retrieve from.
585
586 \return A pointer to the thread's errno.
587*/
589
590/** \brief Retrieve a pointer to the thread reent struct.
591 \relatesalso kthread_t
592
593 This function is used to retrieve some internal state that is used by
594 newlib to provide a reentrant libc.
595
596 \param thd The thread to retrieve from.
597
598 \return The thread's reent struct.
599*/
600struct _reent *thd_get_reent(kthread_t *thd);
601
602/** \brief Retrieves the thread's elapsed CPU time
603 \relatesalso kthread_t
604
605 Returns the amount of active CPU time the thread has consumed in
606 nanoseconds.
607
608 \param thd The thead to retrieve the CPU time for.
609
610 \retval Total utilized CPU time in nanoseconds.
611*/
613
614/** \brief Retrieves all thread's elapsed CPU time
615 \relatesalso kthread_t
616
617 Returns the amount of active CPU time all threads have consumed in
618 nanoseconds.
619
620 \retval Total utilized CPU time in nanoseconds.
621*/
623
624/** \brief Change threading modes.
625
626 This function changes the current threading mode of the system.
627 With preemptive threading being the only mode.
628
629 \deprecated
630 This is now deprecated
631
632 \param mode One of the THD_MODE values.
633
634 \return The old mode of the threading system.
635
636 \sa thd_get_mode
637*/
639
640/** \brief Fetch the current threading mode.
641
642 With preemptive threading being the only mode.
643
644 \deprecated
645 This is now deprecated.
646
647 \return The current mode of the threading system.
648
649 \sa thd_set_mode
650*/
652
653/** \brief Set the scheduler's frequency.
654
655 Sets the frequency of the scheduler interrupts in hertz.
656
657 \param hertz The new frequency in hertz (1-1000)
658
659 \retval 0 The frequency was updated successfully.
660 \retval -1 \p hertz is invalid.
661
662 \sa thd_get_hz(), HZ
663*/
664int thd_set_hz(unsigned int hertz);
665
666/** \brief Fetch the scheduler's current frequency.
667
668 Queries the scheduler for its interrupt frequency in hertz.
669
670 \return Scheduler frequency in hertz.
671
672 \sa thd_set_hz(), HZ
673*/
674unsigned thd_get_hz(void);
675
676/** \brief Wait for a thread to exit.
677 \relatesalso kthread_t
678
679 This function "joins" a joinable thread. This means effectively that the
680 calling thread blocks until the speified thread completes execution. It is
681 invalid to join a detached thread, only joinable threads may be joined.
682
683 \param thd The joinable thread to join.
684 \param value_ptr A pointer to storage for the thread's return value,
685 or NULL if you don't care about it.
686
687 \return 0 on success, or less than 0 if the thread is
688 non-existent or not joinable.
689
690 \sa thd_detach
691*/
692int thd_join(kthread_t *thd, void **value_ptr);
693
694/** \brief Detach a joinable thread.
695 \relatesalso kthread_t
696
697 This function switches the specified thread's mode from THD_MODE_JOINABLE
698 to THD_MODE_DETACHED. This will ensure that the thread cleans up all of its
699 internal resources when it exits.
700
701 \param thd The joinable thread to detach.
702
703 \return 0 on success or less than 0 if the thread is
704 non-existent or already detached.
705 \sa thd_join()
706*/
708
709/** \brief Iterate all threads and call the passed callback for each
710 \relatesalso kthread_t
711
712 \param cb The callback to call for each thread.
713 If a nonzero value is returned, iteration
714 ceases immediately.
715 \param data User data to be passed to the callback
716
717 \retval 0 or the first nonzero value returned by \p cb.
718
719 \sa thd_pslist
720*/
721int thd_each(int (*cb)(kthread_t *thd, void *user_data), void *data);
722
723/** \brief Print a list of all threads using the given print function.
724
725 Each thread is printed with its address, tid, priority level, flags,
726 it's wait timeout (if sleeping) the amount of cpu time usage in ns
727 (this includes time in IRQs), state, and name.
728
729 In addition a '[system]' item is provided that represents time since
730 initialization not spent in a thread (context switching, updating
731 wait timeouts, etc).
732
733 \param pf The printf-like function to print with.
734
735 \retval 0 On success.
736
737 \sa thd_pslist_queue
738*/
739int thd_pslist(int (*pf)(const char *fmt, ...));
740
741/** \brief Print a list of all queued threads using the given print function.
742
743 \param pf The printf-like function to print with.
744
745 \retval 0 On success.
746
747 \sa thd_pslist
748*/
749int thd_pslist_queue(int (*pf)(const char *fmt, ...));
750
751/** \cond INTERNAL */
752
753/** \brief Initialize the threading system.
754
755 This is normally done for you by default when KOS starts. This will also
756 initialize all the various synchronization primitives.
757 \retval -1 If threads are already initialized.
758 \retval 0 On success.
759 \sa thd_shutdown
760*/
761int thd_init(void);
762
763
764/** \brief Shutdown the threading system.
765
766 This is done for you by the normal shutdown procedure of KOS. This will
767 also shutdown all the various synchronization primitives.
768
769 \sa thd_init
770*/
771void thd_shutdown(void);
772
773/** \endcond */
774
775/** @} */
776
777__END_DECLS
778
779#endif /* __KOS_THREAD_H */
Definitions for builtin attributes and compiler directives.
irq_context_t * thd_choose_new(void)
Find a new thread to swap in.
kthread_mode_t thd_get_mode(void) __deprecated
Fetch the current threading mode.
int thd_set_hz(unsigned int hertz)
Set the scheduler's frequency.
int thd_each(int(*cb)(kthread_t *thd, void *user_data), void *data)
Iterate all threads and call the passed callback for each.
void thd_exit(void *rv) __noreturn
Exit the current thread.
int thd_remove_from_runnable(kthread_t *thd)
Removes a thread from the runnable queue, if it's there.
void thd_schedule(bool front_of_line, uint64_t now)
Force a thread reschedule.
uint64_t thd_get_total_cpu_time(void)
Retrieves all thread's elapsed CPU time.
struct _reent * thd_get_reent(kthread_t *thd)
Retrieve a pointer to the thread reent struct.
int thd_destroy(kthread_t *thd)
Brutally kill the given thread.
int thd_block_now(irq_context_t *mycxt)
Block the current thread.
unsigned thd_get_hz(void)
Fetch the scheduler's current frequency.
uint64_t thd_get_cpu_time(kthread_t *thd)
Retrieves the thread's elapsed CPU time.
const char * thd_get_pwd(kthread_t *thd)
Retrieve the thread's current working directory.
void thd_add_to_runnable(kthread_t *t, bool front_of_line)
Enqueue a process in the runnable queue.
int thd_detach(kthread_t *thd)
Detach a joinable thread.
int thd_set_prio(kthread_t *thd, prio_t prio)
Set a thread's priority value.
void thd_schedule_next(kthread_t *thd)
Force a given thread to the front of the queue.
kthread_t * thd_create(bool detach, void *(*routine)(void *param), void *param)
Create a new thread.
#define KTHREAD_LABEL_SIZE
Size of a kthread's label.
Definition thread.h:105
kthread_state_t
Kernel thread state.
Definition thread.h:144
int thd_join(kthread_t *thd, void **value_ptr)
Wait for a thread to exit.
kthread_mode_t
kthread mode values
Definition thread.h:301
int * thd_get_errno(kthread_t *thd)
Retrieve a pointer to the thread errno.
kthread_t * thd_by_tid(tid_t tid)
Given a thread ID, locates the thread structure.
void thd_sleep(unsigned ms)
Sleep for a given number of milliseconds.
kthread_t * thd_get_current(void)
Retrieve the current thread's kthread struct.
uint8_t kthread_flags_t
Kernel thread flags type.
Definition thread.h:138
void thd_set_pwd(kthread_t *thd, const char *__RESTRICT pwd)
Set the thread's current working directory.
const char * thd_get_label(kthread_t *thd)
Retrieve the thread's label.
kthread_t * thd_create_ex(const kthread_attr_t *__RESTRICT attr, void *(*routine)(void *param), void *param)
Create a new thread with the specified set of attributes.
int thd_pslist_queue(int(*pf)(const char *fmt,...))
Print a list of all queued threads using the given print function.
int thd_pslist(int(*pf)(const char *fmt,...))
Print a list of all threads using the given print function.
int thd_set_mode(kthread_mode_t mode) __deprecated
Change threading modes.
#define KTHREAD_PWD_SIZE
Size of a kthread's current directory.
Definition thread.h:112
void thd_pass(void)
Throw away the current thread's timeslice.
void thd_set_label(kthread_t *thd, const char *__RESTRICT label)
Set the thread's label.
@ STATE_READY
Ready to be scheduled.
Definition thread.h:147
@ STATE_FINISHED
Finished execution.
Definition thread.h:149
@ STATE_WAIT
Blocked on a genwait.
Definition thread.h:148
@ STATE_RUNNING
Process is "current".
Definition thread.h:146
@ STATE_ZOMBIE
Waiting to die.
Definition thread.h:145
@ THD_MODE_NONE
Threads not running.
Definition thread.h:302
@ THD_MODE_PREEMPT
Preemptive threading mode.
Definition thread.h:304
@ THD_MODE_COOP
Cooperative mode.
Definition thread.h:303
#define __RESTRICT
Definition cdefs.h:181
#define __deprecated
Mark something as deprecated.
Definition cdefs.h:114
#define __noreturn
Identify a function that will never return.
Definition cdefs.h:45
typedef LIST_HEAD(nmmgr_list, nmmgr_handler) nmmgr_list_t
Name handler list type.
handle_t prio_t
Priority value type.
Definition types.h:61
handle_t tid_t
Thread ID type.
Definition types.h:60
Interrupt and exception handling.
Architecture-specific structure for holding the processor state.
Definition irq.h:96
Thread creation attributes.
Definition thread.h:275
prio_t prio
Set the thread's priority.
Definition thread.h:287
void * stack_ptr
Pre-allocate a stack for the thread.
Definition thread.h:284
const char * label
Thread label.
Definition thread.h:290
bool create_detached
1 for a detached thread.
Definition thread.h:277
size_t stack_size
Set the size of the stack to be created.
Definition thread.h:280
Structure describing one running thread.
Definition thread.h:160
irq_context_t context
Register store – used to save thread context.
Definition thread.h:162
tid_t tid
Kernel thread id.
Definition thread.h:174
kthread_flags_t flags
Thread flags.
Definition thread.h:183
int thd_errno
Thread errno variable.
Definition thread.h:242
uint64_t wait_timeout
Next scheduled time.
Definition thread.h:215
uint64_t scheduled
time when the thread became active
Definition thread.h:219
uint64_t total
total running CPU time for thread
Definition thread.h:220
kthread_state_t state
Process state.
Definition thread.h:186
void * stack
Thread private stack.
Definition thread.h:236
void * rv
Return value of the thread function.
Definition thread.h:260
void * wait_obj
Generic wait target, if waiting.
Definition thread.h:192
TAILQ_ENTRY(kthread) timerq
Timer queue handle (if applicable).
prio_t prio
Dynamic priority.
Definition thread.h:177
LIST_ENTRY(kthread) t_list
Thread list handle.
void * tls_hnd
Compiler-level thread-local storage.
Definition thread.h:254
TAILQ_ENTRY(kthread) thdq
Run/Wait queue handle.
const char * wait_msg
Generic wait message, if waiting.
Definition thread.h:198
prio_t real_prio
Static priority: 0..PRIO_MAX (higher means lower priority).
Definition thread.h:180
size_t stack_size
Size of the thread's stack, in bytes.
Definition thread.h:239
Thread-local storage support.