SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
Threads

Typedefs

typedef enum cy_thread_state cy_thread_state_t
typedef void(* cy_thread_entry_fn_t) (cy_thread_arg_t arg)

Enumerations

enum  cy_thread_state {
  CY_THREAD_STATE_INACTIVE ,
  CY_THREAD_STATE_READY ,
  CY_THREAD_STATE_RUNNING ,
  CY_THREAD_STATE_BLOCKED ,
  CY_THREAD_STATE_TERMINATED ,
  CY_THREAD_STATE_UNKNOWN
}
cy_rslt_t cy_rtos_thread_create (cy_thread_t *thread, cy_thread_entry_fn_t entry_function, const char *name, void *stack, uint32_t stack_size, cy_thread_priority_t priority, cy_thread_arg_t arg)
cy_rslt_t cy_rtos_thread_exit (void)
cy_rslt_t cy_rtos_thread_terminate (const cy_thread_t *thread)
cy_rslt_t cy_rtos_thread_join (cy_thread_t *thread)
cy_rslt_t cy_rtos_thread_is_running (const cy_thread_t *thread, bool *running)
cy_rslt_t cy_rtos_thread_get_state (const cy_thread_t *thread, cy_thread_state_t *state)
cy_rslt_t cy_rtos_thread_get_handle (cy_thread_t *thread)
cy_rslt_t cy_rtos_thread_wait_notification (cy_time_t timeout_ms)
cy_rslt_t cy_rtos_thread_set_notification (const cy_thread_t *thread)
cy_rslt_t cy_rtos_thread_get_name (const cy_thread_t *thread, const char **thread_name)
#define cy_rtos_create_thread(thread, entry_function, name, stack, stack_size, priority, arg)
#define cy_rtos_is_thread_running(thread, running)
#define cy_rtos_set_thread_notification(thread, in_isr)
#define cy_rtos_wait_thread_notification(timeout_ms)
#define cy_rtos_get_thread_state(thread, state)
#define cy_rtos_join_thread(thread)
#define cy_rtos_get_thread_handle(thread)
#define cy_rtos_terminate_thread(thread)
#define cy_rtos_exit_thread   cy_rtos_thread_exit

Detailed Description

APIs for creating and working with Threads.

Macro Definition Documentation

◆ cy_rtos_create_thread

#define cy_rtos_create_thread ( thread,
entry_function,
name,
stack,
stack_size,
priority,
arg )
Value:
cy_rtos_thread_create(thread, entry_function, name, stack, stack_size, priority, arg)
cy_rslt_t cy_rtos_thread_create(cy_thread_t *thread, cy_thread_entry_fn_t entry_function, const char *name, void *stack, uint32_t stack_size, cy_thread_priority_t priority, cy_thread_arg_t arg)

Create a thread with specific thread argument.

This function is called to startup a new thread. If the thread can exit, it must call cy_rtos_exit_thread() just before doing so. All created threads that can terminate, either by themselves or forcefully by another thread MUST have cy_rtos_join_thread() called on them by another thread in order to cleanup any resources that might have been allocated for them.

Parameters
[out]threadPointer to a variable which will receive the new thread handle
[in]entry_functionFunction pointer which points to the main function for the new thread
[in]nameString thread name used for a debugger
[in]stackThe buffer to use for the thread stack. This must be aligned to CY_RTOS_ALIGNMENT_MASK with a size of at least CY_RTOS_MIN_STACK_SIZE. If stack is null, cy_rtos_create_thread will allocate a stack from the heap.
[in]stack_sizeThe size of the thread stack in bytes
[in]priorityThe priority of the thread. Values are operating system specific, but some common priority levels are defined: CY_THREAD_PRIORITY_LOW CY_THREAD_PRIORITY_NORMAL CY_THREAD_PRIORITY_HIGH
[in]argThe argument to pass to the new thread
Returns
The status of thread create request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_BAD_PARAM, CY_RTOS_ALIGNMENT_ERROR].
Specific for kernel:

Definition at line 1002 of file cyabs_rtos.h.

1002#define cy_rtos_create_thread(thread, entry_function, name, stack, stack_size, priority, arg) \
1003 cy_rtos_thread_create(thread, entry_function, name, stack, stack_size, priority, arg)

◆ cy_rtos_exit_thread

#define cy_rtos_exit_thread   cy_rtos_thread_exit

Exit the current thread.

This function is called just before a thread exits. In some cases it is sufficient for a thread to just return to exit, but in other cases, the RTOS must be explicitly signaled. In cases where a return is sufficient, this should be a null function. In cases where the RTOS must be signaled, this function should perform that operation. In code using RTOS services, this function should be placed at any location where the main thread function will return, exiting the thread. Threads that can exit must still be joined (cy_rtos_join_thread) to ensure their resources are fully cleaned up.

Returns
The status of thread exit request only for FreeRTOS. [CY_RSLT_SUCCESS].

Definition at line 1125 of file cyabs_rtos.h.

◆ cy_rtos_get_thread_handle

#define cy_rtos_get_thread_handle ( thread)
Value:
cy_rslt_t cy_rtos_thread_get_handle(cy_thread_t *thread)

Get current thread handle

Returns the unique thread handle of the current running thread.

Parameters
[out]threadHandle of the current running thread
Returns
The status of thread join request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].

Definition at line 1090 of file cyabs_rtos.h.

◆ cy_rtos_get_thread_state

#define cy_rtos_get_thread_state ( thread,
state )
Value:
cy_rslt_t cy_rtos_thread_get_state(const cy_thread_t *thread, cy_thread_state_t *state)

Gets the state the thread is currently in

This function is called to determine if a thread is running/blocked/inactive/ready etc.

Parameters
[in]threadHandle of the terminated thread to delete
[out]stateReturns the state the thread is currently in
Returns
The status of the thread state check. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 1063 of file cyabs_rtos.h.

◆ cy_rtos_is_thread_running

#define cy_rtos_is_thread_running ( thread,
running )
Value:
cy_rtos_thread_is_running(thread, running)
cy_rslt_t cy_rtos_thread_is_running(const cy_thread_t *thread, bool *running)

Checks if the thread is running

This function is called to determine if a thread is actively running or not. For information on the thread state, use the cy_rtos_get_thread_state() function.

Parameters
[in]threadHandle of the terminated thread to delete
[out]runningReturns true if the thread is running, otherwise false
Returns
The status of the thread running check. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].

Definition at line 1016 of file cyabs_rtos.h.

1016#define cy_rtos_is_thread_running(thread, running) \
1017 cy_rtos_thread_is_running(thread, running)

◆ cy_rtos_join_thread

#define cy_rtos_join_thread ( thread)
Value:
cy_rslt_t cy_rtos_thread_join(cy_thread_t *thread)

Waits for a thread to complete.

This must be called on any thread that can complete to ensure that any resources that were allocated for it are cleaned up.

Parameters
[in]threadHandle of the thread to wait for
Returns
The status of thread join request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 1079 of file cyabs_rtos.h.

◆ cy_rtos_set_thread_notification

#define cy_rtos_set_thread_notification ( thread,
in_isr )
Value:
cy_rslt_t cy_rtos_thread_set_notification(const cy_thread_t *thread)

Set the thread notification for a thread

This function sets the thread notification for the target thread. The target thread waiting for the notification to be set will resume from suspended state.

Parameters
[in]threadHandle of the target thread
[in]in_isrIf true this is being called from within an ISR
Returns
The status of thread wait. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 1032 of file cyabs_rtos.h.

1032#define cy_rtos_set_thread_notification(thread, in_isr) \
1033 cy_rtos_thread_set_notification(thread)

◆ cy_rtos_terminate_thread

#define cy_rtos_terminate_thread ( thread)
Value:
cy_rslt_t cy_rtos_thread_terminate(const cy_thread_t *thread)

Terminates another thread.

This function is called to terminate another thread and reap the resources claimed by the thread. This should be called both when forcibly terminating another thread as well as any time a thread can exit on its own. For some RTOS implementations this is not required as the thread resources are claimed as soon as it exits. In other cases, this must be called to reclaim resources. Threads that are terminated must still be joined (cy_rtos_join_thread) to ensure their resources are fully cleaned up.

Parameters
[in]threadHandle of the thread to terminate
Returns
The status of the thread terminate. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 1110 of file cyabs_rtos.h.

◆ cy_rtos_wait_thread_notification

#define cy_rtos_wait_thread_notification ( timeout_ms)
Value:
cy_rslt_t cy_rtos_thread_wait_notification(cy_time_t timeout_ms)

Suspend current thread until notification is received

This function suspends the execution of current thread until it is notified by cy_rtos_set_thread_notification from another thread or ISR, or timed out with specify timeout value

Parameters
[in]timeout_msMaximum number of milliseconds to wait Use the CY_RTOS_NEVER_TIMEOUT constant to wait forever.
Returns
The status of thread wait. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_TIMEOUT].
Specific for kernel:

Definition at line 1049 of file cyabs_rtos.h.

Typedef Documentation

◆ cy_thread_entry_fn_t

typedef void(* cy_thread_entry_fn_t) (cy_thread_arg_t arg)

The type of a function that is the entry point for a thread

Parameters
[in]argthe argument passed from the thread create call to the entry function

Definition at line 179 of file cyabs_rtos.h.

◆ cy_thread_state_t

The state a thread can be in

Enumeration Type Documentation

◆ cy_thread_state

The state a thread can be in

Enumerator
CY_THREAD_STATE_INACTIVE 

thread has not started or was terminated but not yet joined

CY_THREAD_STATE_READY 

thread can run, but is not currently

CY_THREAD_STATE_RUNNING 

thread is currently running

CY_THREAD_STATE_BLOCKED 

thread is blocked waiting for something

CY_THREAD_STATE_TERMINATED 

thread has terminated but not freed

CY_THREAD_STATE_UNKNOWN 

thread is in an unknown state

Definition at line 129 of file cyabs_rtos.h.

130{
enum cy_thread_state cy_thread_state_t
@ CY_THREAD_STATE_BLOCKED
Definition cyabs_rtos.h:134
@ CY_THREAD_STATE_INACTIVE
Definition cyabs_rtos.h:131
@ CY_THREAD_STATE_RUNNING
Definition cyabs_rtos.h:133
@ CY_THREAD_STATE_UNKNOWN
Definition cyabs_rtos.h:136
@ CY_THREAD_STATE_READY
Definition cyabs_rtos.h:132
@ CY_THREAD_STATE_TERMINATED
Definition cyabs_rtos.h:135

Function Documentation

◆ cy_rtos_thread_create()

cy_rslt_t cy_rtos_thread_create ( cy_thread_t * thread,
cy_thread_entry_fn_t entry_function,
const char * name,
void * stack,
uint32_t stack_size,
cy_thread_priority_t priority,
cy_thread_arg_t arg )

Create a thread with specific thread argument.

This function is called to startup a new thread. If the thread can exit, it must call cy_rtos_thread_exit() just before doing so. All created threads that can terminate, either by themselves or forcefully by another thread MUST have cy_rtos_thread_join() called on them by another thread in order to cleanup any resources that might have been allocated for them.

Parameters
[out]threadPointer to a variable which will receive the new thread handle
[in]entry_functionFunction pointer which points to the main function for the new thread
[in]nameString thread name used for a debugger
[in]stackThe buffer to use for the thread stack. This must be aligned to CY_RTOS_ALIGNMENT_MASK with a size of at least CY_RTOS_MIN_STACK_SIZE. If stack is null, cy_rtos_create_thread will allocate a stack from the heap.
[in]stack_sizeThe size of the thread stack in bytes
[in]priorityThe priority of the thread. Values are operating system specific, but some common priority levels are defined: CY_THREAD_PRIORITY_LOW CY_THREAD_PRIORITY_NORMAL CY_THREAD_PRIORITY_HIGH
[in]argThe argument to pass to the new thread
Returns
The status of thread create request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_BAD_PARAM, CY_RTOS_ALIGNMENT_ERROR].
Specific for kernel:

< not allowed in this context (ISR, scheduler not running or locked, not a thread created by cy_rtos_thread_create())

< no error

< thread or its stack is already known to the kernel

< kernel is not initialized (see cy_rtos_stk_kernel_init())

Examples
blinky_c-cyabs_rtos/example.c.

Definition at line 441 of file cyabs_rtos_stk.cpp.

444{
445 const uintptr_t stack_align = STK_STACK_MEMORY_ALIGN;
446
447 if (0U != (stack_size & CY_RTOS_ALIGNMENT_MASK))
448 {
450 }
451 if ((thread == nullptr) || (entry_function == nullptr) || (stack_size < CY_RTOS_MIN_STACK_SIZE) ||
452 (static_cast<uint32_t>(priority) >= CY_RTOS_STK_PRIORITY_LEVELS))
453 {
454 return CY_RTOS_BAD_PARAM;
455 }
456 if ((stack != nullptr) && (0U != (reinterpret_cast<uintptr_t>(stack) & (stack_align - 1U))))
457 {
459 }
460 if (InIsr())
461 {
462 return Fail(CY_RTOS_STK_ERR_CONTEXT);
463 }
464
465 // one block: control block, and the stack unless the caller supplied it
466 const size_t hdr = static_cast<size_t>(AlignUp(sizeof(cy_stk_thread), stack_align));
467 size_t total = hdr;
468 if (stack == nullptr)
469 {
470 total += (static_cast<size_t>(stack_size) + stack_align); // + room for aligning the stack start
471 }
472
473 void *const raw = CY_RTOS_STK_MALLOC(total);
474 if (raw == nullptr)
475 {
476 return CY_RTOS_NO_MEMORY;
477 }
478
479 if (stack == nullptr)
480 {
481 stack = reinterpret_cast<void *>(AlignUp(reinterpret_cast<uintptr_t>(raw) + hdr, stack_align));
482 }
483
484 cy_stk_thread *const th = new (raw) cy_stk_thread(entry_function, arg, name,
485 static_cast<stk::Word *>(stack), (stack_size / sizeof(stk::Word)), raw,
486 static_cast<uint32_t>(priority));
487
488 RegistryAdd(th);
489 *thread = th; // before the thread can run
490
491 cy_rslt_t result;
492
493 switch (g_Kernel.AddTask(th))
494 {
495 case stk::ADD_OK:
496 result = CY_RSLT_SUCCESS;
497 break;
498 case stk::ADD_FAIL_POOL_FULL: // increase CY_RTOS_STK_MAX_THREADS
499 g_LastError = CY_RTOS_STK_ERR_NONE;
500 result = CY_RTOS_NO_MEMORY;
501 break;
503 result = Fail(CY_RTOS_STK_ERR_DUPLICATE);
504 break;
505 default: // ADD_FAIL_INVALID: cy_rtos_stk_kernel_init() was not called
506 result = Fail(CY_RTOS_STK_ERR_KERNEL_STATE);
507 break;
508 }
509
510 if (result != CY_RSLT_SUCCESS)
511 {
512 *thread = nullptr;
513 RegistryRemove(th);
514 th->m_magic = 0U;
515 th->~cy_stk_thread();
516 CY_RTOS_STK_FREE(raw);
517 }
518
519 return result;
520}
#define STK_STACK_MEMORY_ALIGN
Stack memory alignment.
Definition stk_defs.h:582
#define CY_RTOS_ALIGNMENT_MASK
#define CY_RTOS_MIN_STACK_SIZE
#define CY_RTOS_STK_ERR_NONE
#define CY_RTOS_STK_ERR_CONTEXT
#define CY_RTOS_STK_ERR_DUPLICATE
#define CY_RTOS_STK_ERR_KERNEL_STATE
#define CY_RTOS_STK_PRIORITY_LEVELS
#define CY_RTOS_STK_MALLOC(size)
#define CY_RTOS_STK_FREE(ptr)
#define CY_RTOS_BAD_PARAM
Definition cyabs_rtos.h:96
#define CY_RTOS_NO_MEMORY
Definition cyabs_rtos.h:90
#define CY_RTOS_ALIGNMENT_ERROR
Definition cyabs_rtos.h:100
uintptr_t Word
Native processor word type.
Definition stk_common.h:206
@ ADD_FAIL_POOL_FULL
No free kernel slot left (TASKS_MAX reached). In KERNEL_DYNAMIC mode retry later, once a task has exi...
Definition stk_common.h:152
@ ADD_OK
Task was added.
Definition stk_common.h:153
@ ADD_FAIL_DUPLICATE
The task (or its stack) is already added to the kernel. Application design failure.
Definition stk_common.h:151
virtual ~cy_stk_thread()
static stk_kernel_t * g_Kernel

References stk::ADD_FAIL_DUPLICATE, stk::ADD_FAIL_POOL_FULL, stk::ADD_OK, CY_RTOS_ALIGNMENT_ERROR, CY_RTOS_ALIGNMENT_MASK, CY_RTOS_BAD_PARAM, CY_RTOS_MIN_STACK_SIZE, CY_RTOS_NO_MEMORY, CY_RTOS_STK_ERR_CONTEXT, CY_RTOS_STK_ERR_DUPLICATE, CY_RTOS_STK_ERR_KERNEL_STATE, CY_RTOS_STK_ERR_NONE, CY_RTOS_STK_FREE, CY_RTOS_STK_MALLOC, CY_RTOS_STK_PRIORITY_LEVELS, g_Kernel, cy_stk_thread::m_magic, STK_STACK_MEMORY_ALIGN, and cy_stk_thread::~cy_stk_thread().

Referenced by app_init(), and app_main().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ cy_rtos_thread_exit()

cy_rslt_t cy_rtos_thread_exit ( void )

Exit the current thread.

This function is called just before a thread exits. In some cases it is sufficient for a thread to just return to exit, but in other cases, the RTOS must be explicitly signaled. In cases where a return is sufficient, this should be a null function. In cases where the RTOS must be signaled, this function should perform that operation. In code using RTOS services, this function should be placed at any location where the main thread function will return, exiting the thread. Threads that can exit must still be joined (cy_rtos_thread_join) to ensure their resources are fully cleaned up.

Returns
The status of thread exit request only for FreeRTOS. [CY_RSLT_SUCCESS].

< not allowed in this context (ISR, scheduler not running or locked, not a thread created by cy_rtos_thread_create())

Definition at line 522 of file cyabs_rtos_stk.cpp.

523{
524 cy_stk_thread *const th = CurrentThread();
525
526 if (th == nullptr)
527 {
528 return Fail(CY_RTOS_STK_ERR_CONTEXT);
529 }
530
531 // Like RTX/FreeRTOS: does not return. (Returning from the entry function is equivalent.)
532 th->m_finished = true;
534
535 return CY_RSLT_SUCCESS;
536}
static void ExitTask()
Terminate the calling task: schedule its removal and switch it out. Does not return.
Definition stk_helper.h:578
volatile bool m_finished

References CY_RTOS_STK_ERR_CONTEXT, stk::ExitTask(), and cy_stk_thread::m_finished.

Here is the call graph for this function:

◆ cy_rtos_thread_get_handle()

cy_rslt_t cy_rtos_thread_get_handle ( cy_thread_t * thread)

Get current thread handle

Returns the unique thread handle of the current running thread.

Parameters
[out]threadHandle of the current running thread
Returns
The status of thread join request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].

< not allowed in this context (ISR, scheduler not running or locked, not a thread created by cy_rtos_thread_create())

Definition at line 697 of file cyabs_rtos_stk.cpp.

698{
699 if (thread == nullptr)
700 {
701 return CY_RTOS_BAD_PARAM;
702 }
703
704 cy_stk_thread *const th = CurrentThread();
705
706 if (th == nullptr)
707 {
708 return Fail(CY_RTOS_STK_ERR_CONTEXT); // ISR, or not a thread of the abstraction layer
709 }
710
711 *thread = th;
712
713 return CY_RSLT_SUCCESS;
714}

References CY_RTOS_BAD_PARAM, and CY_RTOS_STK_ERR_CONTEXT.

◆ cy_rtos_thread_get_name()

cy_rslt_t cy_rtos_thread_get_name ( const cy_thread_t * thread,
const char ** thread_name )

Get the name of a thread

This function returns the name of the target thread

Parameters
[in]threadHandle of the target thread
[out]thread_nameWill be updated to point to the thread name. Can return NULL in the case of no thread name.
Returns
The status of getting the thread name. Same across all RTOS kernels [CY_RSLT_SUCCESS].
Specific for kernel:

Definition at line 753 of file cyabs_rtos_stk.cpp.

754{
755 cy_stk_thread *const th = ValidThread(thread);
756
757 if ((th == nullptr) || (thread_name == nullptr))
758 {
759 return CY_RTOS_BAD_PARAM;
760 }
761
762 *thread_name = th->m_name;
763
764 return CY_RSLT_SUCCESS;
765}
const char * m_name

References CY_RTOS_BAD_PARAM, and cy_stk_thread::m_name.

◆ cy_rtos_thread_get_state()

cy_rslt_t cy_rtos_thread_get_state ( const cy_thread_t * thread,
cy_thread_state_t * state )

Gets the state the thread is currently in

This function is called to determine if a thread is running/blocked/inactive/ready etc.

Parameters
[in]threadHandle of the terminated thread to delete
[out]stateReturns the state the thread is currently in
Returns
The status of the thread state check. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 648 of file cyabs_rtos_stk.cpp.

649{
650 cy_stk_thread *const th = ValidThread(thread);
651
652 if ((th == nullptr) || (state == nullptr))
653 {
654 return CY_RTOS_BAD_PARAM;
655 }
656
657 if (th == CurrentThread())
658 {
660 }
661 else if (th->m_removed || th->m_finished)
662 {
664 }
665 else
666 {
668
669 if (!g_Kernel.GetTaskState(th, info))
670 {
672 }
673 else
674 {
675 switch (info.state)
676 {
681 break;
684 break;
686 case stk::TASK_STATE_REMOVED: // added, not bound by a running kernel yet
687 default:
688 *state = CY_THREAD_STATE_READY;
689 break;
690 }
691 }
692 }
693
694 return CY_RSLT_SUCCESS;
695}
@ TASK_STATE_EXITING
Run() has returned, the slot is released on the next tick (KERNEL_DYNAMIC mode only).
Definition stk_common.h:88
@ TASK_STATE_SLEEPING
Sleeping via Sleep()/SleepUntil(), with a finite or an infinite timeout.
Definition stk_common.h:85
@ TASK_STATE_SUSPENDED
Suspended by IKernel::SuspendTask().
Definition stk_common.h:87
@ TASK_STATE_REMOVED
The task is not bound to a kernel slot (never added, or already removed).
Definition stk_common.h:83
@ TASK_STATE_WAITING
Blocked on a synchronization object (IKernelService::Wait). KERNEL_SYNC mode only.
Definition stk_common.h:86
@ TASK_STATE_READY
Runnable: running, or waiting for the CPU.
Definition stk_common.h:84
static constexpr Timeout WAIT_INFINITE
Timeout value: block indefinitely until the synchronization object is signaled.
Definition stk_common.h:274
Snapshot of the kernel-side state of a task, filled in by IKernel::GetTaskState().
Definition stk_common.h:384
ETaskState state
Task state.
Definition stk_common.h:385
volatile bool m_removed

References CY_RTOS_BAD_PARAM, CY_THREAD_STATE_BLOCKED, CY_THREAD_STATE_READY, CY_THREAD_STATE_RUNNING, CY_THREAD_STATE_TERMINATED, CY_THREAD_STATE_UNKNOWN, g_Kernel, cy_stk_thread::m_finished, cy_stk_thread::m_removed, stk::TaskStateInfo::state, stk::TASK_STATE_EXITING, stk::TASK_STATE_READY, stk::TASK_STATE_REMOVED, stk::TASK_STATE_SLEEPING, stk::TASK_STATE_SUSPENDED, stk::TASK_STATE_WAITING, and stk::WAIT_INFINITE.

◆ cy_rtos_thread_is_running()

cy_rslt_t cy_rtos_thread_is_running ( const cy_thread_t * thread,
bool * running )

Checks if the thread is running

This function is called to determine if a thread is actively running or not. For information on the thread state, use the cy_rtos_thread_get_state() function.

Parameters
[in]threadHandle of the terminated thread to delete
[out]runningReturns true if the thread is running, otherwise false
Returns
The status of the thread running check. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].

Definition at line 633 of file cyabs_rtos_stk.cpp.

634{
635 cy_stk_thread *const th = ValidThread(thread);
636
637 if ((th == nullptr) || (running == nullptr))
638 {
639 return CY_RTOS_BAD_PARAM;
640 }
641
642 // Only the calling thread is running (single core)
643 *running = (th == CurrentThread());
644
645 return CY_RSLT_SUCCESS;
646}

References CY_RTOS_BAD_PARAM.

◆ cy_rtos_thread_join()

cy_rslt_t cy_rtos_thread_join ( cy_thread_t * thread)

Waits for a thread to complete.

This must be called on any thread that can complete to ensure that any resources that were allocated for it are cleaned up.

Parameters
[in]threadHandle of the thread to wait for
Returns
The status of thread join request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

< not allowed in this context (ISR, scheduler not running or locked, not a thread created by cy_rtos_thread_create())

< the kernel rejected the wait / sleep

Definition at line 592 of file cyabs_rtos_stk.cpp.

593{
594 cy_stk_thread *const th = ValidThread(thread);
595
596 if (th == nullptr)
597 {
598 return CY_RTOS_BAD_PARAM;
599 }
600 if (th == CurrentThread())
601 {
602 return CY_RTOS_BAD_PARAM; // joining itself never completes
603 }
604
605 // Blocks until the kernel has removed the task (OnExit() signals m_join), no polling: the CPU can
606 // stay in a low-power state, also with the tickless kernel.
607 while (!th->m_removed)
608 {
609 if (InIsr() || !SchedulerRunning())
610 {
611 return Fail(CY_RTOS_STK_ERR_CONTEXT);
612 }
613
614 // a cancelled wait is harmless (the predicate is re-checked), a rejected one is an error
616 {
617 return Fail(CY_RTOS_STK_ERR_WAIT_FAILED);
618 }
619 }
620
621 void *const raw = th->m_raw;
622
623 RegistryRemove(th);
624 th->m_magic = 0U;
625 th->~cy_stk_thread();
626 CY_RTOS_STK_FREE(raw);
627
628 *thread = nullptr;
629
630 return CY_RSLT_SUCCESS;
631}
#define CY_RTOS_STK_ERR_WAIT_FAILED
@ WAIT_RESULT_FAIL
IKernelService::Wait returned with error without waiting.
Definition stk_common.h:139
EWaitResult WaitEx(Timeout timeout_ticks=WAIT_INFINITE)
Wait for a signal (decrement counter), preserving the full wait outcome.
stk::sync::SemaphoreT< uint16_t > m_join

References CY_RTOS_BAD_PARAM, CY_RTOS_STK_ERR_CONTEXT, CY_RTOS_STK_ERR_WAIT_FAILED, CY_RTOS_STK_FREE, cy_stk_thread::m_join, cy_stk_thread::m_magic, cy_stk_thread::m_raw, cy_stk_thread::m_removed, stk::WAIT_INFINITE, stk::WAIT_RESULT_FAIL, stk::sync::SemaphoreT< T >::WaitEx(), and cy_stk_thread::~cy_stk_thread().

Here is the call graph for this function:

◆ cy_rtos_thread_set_notification()

cy_rslt_t cy_rtos_thread_set_notification ( const cy_thread_t * thread)

Set the thread notification for a thread

This function sets the thread notification for the target thread. The target thread waiting for the notification to be set will resume from suspended state.

Parameters
[in]threadHandle of the target thread
Returns
The status of thread wait. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 738 of file cyabs_rtos_stk.cpp.

739{
740 cy_stk_thread *const th = ValidThread(thread);
741
742 if (th == nullptr)
743 {
744 return CY_RTOS_BAD_PARAM;
745 }
746
747 // ISR-safe. A notification which is already pending is not counted (binary).
748 (void)th->m_notify.TrySignal();
749
750 return CY_RSLT_SUCCESS;
751}
bool TrySignal()
Try to post a signal without exceeding max_count.
stk::sync::SemaphoreT< uint16_t > m_notify

References CY_RTOS_BAD_PARAM, cy_stk_thread::m_notify, and stk::sync::SemaphoreT< T >::TrySignal().

Here is the call graph for this function:

◆ cy_rtos_thread_terminate()

cy_rslt_t cy_rtos_thread_terminate ( const cy_thread_t * thread)

Terminates another thread.

This function is called to terminate another thread and reap the resources claimed by the thread. This should be called both when forcibly terminating another thread as well as any time a thread can exit on its own. For some RTOS implementations this is not required as the thread resources are claimed as soon as it exits. In other cases, this must be called to reclaim resources. Threads that are terminated must still be joined (cy_rtos_thread_join) to ensure their resources are fully cleaned up.

Parameters
[in]threadHandle of the thread to terminate
Returns
The status of the thread terminate. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

< not allowed in this context (ISR, scheduler not running or locked, not a thread created by cy_rtos_thread_create())

< kernel is not initialized (see cy_rtos_stk_kernel_init())

Definition at line 538 of file cyabs_rtos_stk.cpp.

539{
540 cy_stk_thread *const th = ValidThread(thread);
541
542 if (th == nullptr)
543 {
544 return CY_RTOS_BAD_PARAM;
545 }
546 if (InIsr())
547 {
548 return Fail(CY_RTOS_STK_ERR_CONTEXT);
549 }
550
551 const bool is_self = (CurrentThread() == th);
552
553 if (is_self)
554 {
555 th->m_finished = true;
556 stk::ExitTask(); // switched out and removed by the kernel, does not return
557 return CY_RSLT_SUCCESS;
558 }
559
560 // The target may be finishing right now: the check and the removal request are one step with
561 // respect to the kernel tick (which completes the removal and calls OnExit()).
563
564 if (th->m_removed)
565 {
566 return CY_RSLT_SUCCESS; // already gone, join it
567 }
568
569 const stk::IKernel::EKernelState st = KState();
570
572 {
573 return Fail(CY_RTOS_STK_ERR_KERNEL_STATE);
574 }
575
576 th->m_finished = true;
577
579 {
580 g_Kernel.RemoveTask(th); // the kernel has not started: nothing will call OnExit()
581 th->m_removed = true;
582 (void)th->m_join.TrySignal();
583 }
584 else
585 {
586 g_Kernel.ScheduleTaskRemoval(th); // OnExit() fires from the kernel tick
587 }
588
589 return CY_RSLT_SUCCESS;
590}
EKernelState
Kernel state.
@ KSTATE_INACTIVE
Not ready, IKernel::Initialize() must be called.
@ KSTATE_READY
Ready to start, IKernel::Start() must be called.
RAII-style low-level synchronization primitive for atomic code execution. Used as building brick for ...
Definition stk_sync_cs.h:58

References CY_RTOS_BAD_PARAM, CY_RTOS_STK_ERR_CONTEXT, CY_RTOS_STK_ERR_KERNEL_STATE, stk::ExitTask(), g_Kernel, stk::IKernel::KSTATE_INACTIVE, stk::IKernel::KSTATE_READY, cy_stk_thread::m_finished, cy_stk_thread::m_join, cy_stk_thread::m_removed, and stk::sync::SemaphoreT< T >::TrySignal().

Here is the call graph for this function:

◆ cy_rtos_thread_wait_notification()

cy_rslt_t cy_rtos_thread_wait_notification ( cy_time_t timeout_ms)

Suspend current thread until notification is received

This function suspends the execution of current thread until it is notified by cy_rtos_thread_set_notification from another thread or ISR, or timed out with specify timeout value

Parameters
[in]timeout_msMaximum number of milliseconds to wait Use the CY_RTOS_NEVER_TIMEOUT constant to wait forever.
Returns
The status of thread wait. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_TIMEOUT].
Specific for kernel:

< not allowed in this context (ISR, scheduler not running or locked, not a thread created by cy_rtos_thread_create())

Examples
blinky_c-cyabs_rtos/example.c.

Definition at line 718 of file cyabs_rtos_stk.cpp.

719{
720 cy_stk_thread *const th = CurrentThread();
721
722 if (th == nullptr)
723 {
724 return Fail(CY_RTOS_STK_ERR_CONTEXT);
725 }
726
727 stk::Timeout timeout;
728 cy_rslt_t error = CY_RSLT_SUCCESS;
729
730 if (!PrepareTimeout(timeout_ms, timeout, error))
731 {
732 return error;
733 }
734
735 return WaitResultToCy(th->m_notify.WaitEx(timeout), CY_RTOS_TIMEOUT);
736}
#define CY_RTOS_TIMEOUT
Definition cyabs_rtos.h:87
int32_t Timeout
Timeout time (ticks).
Definition stk_common.h:216

References CY_RTOS_STK_ERR_CONTEXT, CY_RTOS_TIMEOUT, cy_stk_thread::m_notify, and stk::sync::SemaphoreT< T >::WaitEx().

Referenced by app_main().

Here is the call graph for this function:
Here is the caller graph for this function: