1.3. thrd
— Threads¶
A thread is the basic execution entity in the OS. A pre-emptive or cooperative scheduler controls the execution of threads.
1.3.1. Scheduler¶
The single core scheduler is configured as cooperative or preemptive at compile time. The cooperative scheduler is implemented for all boards, but the preemptive scheduler is only implemented for a few boards.
There are two threads that are always present; the main thread and the
idle thread. The main thread is the root thread in the system, created
in the main()
function by calling sys_start()
. The idle thread
is running when no other thread is ready to run. It simply waits for
an interrupt to occur and then reschedules to run other ready threads.
The diagram below is an example of how three threads; shell
,
main
and idle
are scheduled over time.
As it is a single core scheduler only one thread is runnng at a
time. In the beginning the system is idle and the idle
thread is
running. After a while the main
and shell
threads have some
work to do, and since they have higher priority than the idle
thread they are scheduled. At the end the idle
thread is running
again.
1.3.2. Debug file system commands¶
Four debug file system commands are available, all located in the
directory kernel/thrd/
.
Command | Description |
---|---|
list |
Print a list of all threads. |
set_log_mask <thread name> <mask> |
Set the log mask of thread <thread name> to mask . |
monitor/set_period_ms <ms> |
Set the monitor thread sampling period to <ms> milliseconds. |
monitor/set_print <state> |
Enable(1 )/disable(0 ) monitor statistics to be printed periodically. |
Example output from the shell:
$ kenel/thrd/list
NAME STATE PRIO CPU LOGMASK
main current 0 0% 0x0f
ready 127 0% 0x0f
ready -80 0% 0x0f
Source code: src/kernel/thrd.h, src/kernel/thrd.c
Test code: tst/kernel/thrd/main.c
Test coverage: src/kernel/thrd.c
Defines
-
THRD_STACK
(name, size)¶ Macro to declare a thread stack with given name and size.
- Parameters
name
-The name of the stack. A variable is declared with this name that should be passed to
thrd_spawn()
.size
-Size of the stack in bytes.
-
THRD_CONTEXT_STORE_ISR
¶ Push all callee-save registers not part of the context struct. The preemptive scheduler requires this macro before the
thrd_yield_isr()
function is called from interrupt context.
-
THRD_CONTEXT_LOAD_ISR
¶ Pop all callee-save registers not part of the context struct. The preemptive scheduler requires this macro after the thrd_yield_isr() function is called from interrupt context.
-
THRD_RESCHEDULE_ISR
¶ Reschuedule from isr. Used by preemptive systems to interrupt low priority threads in favour of high priority threads.
Functions
-
int
thrd_module_init
(void)¶ Initialize the thread module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code
-
struct thrd_t *
thrd_spawn
(void *(*main)(void *), void *arg_p, int prio, void *stack_p, size_t stack_size, )¶ Spawn a thread with given main (entry) function and argument. The thread is initialized and added to the ready queue in the scheduler for execution when prioritized.
- Return
- Thread id, or NULL on error.
- Parameters
main
-Thread main (entry) function. This function normally contains an infinate loop waiting for events to occur.
arg_p
-Main function argument. Passed as arg_p to the main function.
prio
-Thread scheduling priority. [-127..127], where -127 is the highest priority and 127 is the lowest.
stack_p
-Stack pointer. The pointer to a stack created with the macro
THRD_STACK()
.stack_size
-The stack size in number of bytes.
-
int
thrd_suspend
(struct time_t *timeout_p)¶ Suspend current thread and wait to be resumed or a timeout occurs (if given).
- Return
- zero(0), -ETIMEOUT on timeout or other negative error code.
- Parameters
timeout_p
-Time to wait to be resumed before a timeout occurs and the function returns.
-
int
thrd_resume
(struct thrd_t *thrd_p, int err)¶ Resume given thread. If resumed thread is not yet suspended it will not be suspended on next suspend call to
thrd_suspend()
orthrd_suspend_isr()
.- Return
- zero(0) or negative error code.
- Parameters
thrd_p
-Thread id to resume.
err
-Error code to be returned by
thrd_suspend()
orthrd_suspend_isr()
.
-
int
thrd_yield
(void)¶ Put the currently executing thread on the ready list and reschedule.
This function is often called periodically from low priority work heavy threads to give higher priority threads the chance to execute.
- Return
- zero(0) or negative error code.
-
int
thrd_join
(struct thrd_t *thrd_p)¶ Wait for given thread to terminate.
- Return
- zero(0) or negative error code.
- Parameters
thrd_p
-Thread to wait for.
-
int
thrd_sleep
(float seconds)¶ Pauses the current thread for given number of seconds.
- Return
- zero(0) or negative error code.
- Parameters
seconds
-Seconds to sleep.
-
int
thrd_sleep_ms
(int ms)¶ Pauses the current thread for given number of milliseconds.
- Return
- zero(0) or negative error code.
- Parameters
ms
-Milliseconds to sleep.
-
int
thrd_sleep_us
(long us)¶ Pauses the current thread for given number of microseconds.
- Return
- zero(0) or negative error code.
- Parameters
us
-Microseconds to sleep.
-
int
thrd_set_name
(const char *name_p)¶ Set the name of the current thread.
- Return
- zero(0) or negative error code.
- Parameters
name_p
-New thread name.
-
const char *
thrd_get_name
(void)¶ Get the name of the current thread.
- Return
- Current thread name.
-
struct thrd_t *
thrd_get_by_name
(const char *name_p)¶ Get the pointer to given thread.
- Return
- Thraed pointer or NULL if the thread was not found.
-
int
thrd_set_log_mask
(struct thrd_t *thrd_p, int mask)¶ Set the log mask of given thread.
- Return
- Old log mask.
- Parameters
thrd_p
-Thread to set the log mask of.
mask
-Log mask. See the log module for available levels.
-
int
thrd_get_log_mask
(void)¶ Get the log mask of the current thread.
- Return
- Log mask of current thread.
-
int
thrd_set_prio
(struct thrd_t *thrd_p, int prio)¶ Set the priority of given thread.
- Return
- zero(0) or negative error code.
- Parameters
thrd_p
-Thread to set the priority for.
prio
-Priority.
-
int
thrd_get_prio
(void)¶ Get the priority of the current thread.
- Return
- Priority of current thread.
-
int
thrd_init_global_env
(struct thrd_environment_variable_t *variables_p, int length)¶ Initialize the global environment variables storage. These variables are shared among all threads.
- Return
- zero(0) or negative error code.
- Parameters
variables_p
-Variables array.
length
-Length of the variables array.
-
int
thrd_set_global_env
(const char *name_p, const char *value_p)¶ Set the value of given environment variable. The pointers to given name and value are stored in the current global environment array.
- Return
- zero(0) or negative error code.
- Parameters
name_p
-Name of the environment variable to set.
value_p
-Value of the environment variable. Set to NULL to remove the variable.
-
const char *
thrd_get_global_env
(const char *name_p)¶ Get the value of given environment variable in the global environment array.
- Return
- Value of given environment variable or NULL if it is not found.
- Parameters
name_p
-Name of the environment variable to get.
-
int
thrd_init_env
(struct thrd_environment_variable_t *variables_p, int length)¶ Initialize the current threads’ environment variables storage.
- Return
- zero(0) or negative error code.
- Parameters
variables_p
-Variables are to be used by this therad.
length
-Length of the variables array.
-
int
thrd_set_env
(const char *name_p, const char *value_p)¶ Set the value of given environment variable. The pointers to given name and value are stored in the current global environment array.
- Return
- zero(0) or negative error code.
- Parameters
name_p
-Name of the environment variable to set.
value_p
-Value of the environment variable. Set to NULL to remove the variable.
-
const char *
thrd_get_env
(const char *name_p)¶ Get the value of given environment variable. If given variable is not found in the current threads’ environment array, the global environment array is searched.
- Return
- Value of given environment variable or NULL if it is not found.
- Parameters
name_p
-Name of the environment variable to get.
-
int
thrd_suspend_isr
(struct time_t *timeout_p)¶ Suspend current thread with the system lock taken (see
sys_lock()
) and wait to be resumed or a timeout occurs (if given).- Return
- zero(0), -ETIMEOUT on timeout or other negative error code.
- Parameters
timeout_p
-Time to wait to be resumed before a timeout occurs and the function returns.
-
int
thrd_resume_isr
(struct thrd_t *thrd_p, int err)¶ Resume given thread from isr or with the system lock taken (see
sys_lock()
). If resumed thread is not yet suspended it will not be suspended on next suspend call tothrd_suspend()
orthrd_suspend_isr()
.- Return
- zero(0) or negative error code.
- Parameters
thrd_p
-Thread id to resume.
err
-Error code to be returned by
thrd_suspend()
orthrd_suspend_isr()
.
-
int
thrd_yield_isr
(void)¶ Yield current thread from isr (preemptive scheduler only) or with the system lock taken.
- Return
- zero(0) or negative error code.
-
struct
thrd_environment_variable_t
¶ - #include <thrd.h>
A thread environment variable.
-
struct
thrd_environment_t
¶ Public Members
-
struct thrd_environment_variable_t *
variables_p
¶
-
size_t
number_of_variables
¶
-
size_t
max_number_of_variables
¶
-
struct thrd_environment_variable_t *
-
struct
thrd_t
¶