Threads

group group_abstraction_rtos_threads

APIs for creating and working with Threads.

Unnamed Group

cy_rslt_t cy_rtos_create_thread(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.

Return

The status of thread create request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]

Parameters
  • [out] thread: Pointer to a variable which will receive the new thread handle

  • [in] entry_function: Function pointer which points to the main function for the new thread

  • [in] name: String thread name used for a debugger

  • [in] stack: The 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_size: The size of the thread stack in bytes

  • [in] priority: The 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] arg: The argument to pass to the new thread

cy_rslt_t cy_rtos_exit_thread()

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 funcition. where the RTOS must be signaled, this function should perform that In cases operation. In code using RTOS services, this function should be placed at any 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.

Return

The status of thread exit request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]

cy_rslt_t cy_rtos_terminate_thread(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.

Return

The status of the thread terminate. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]

Parameters
  • [in] thread: Handle of the thread to terminate

cy_rslt_t cy_rtos_join_thread(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.

Return

The status of thread join request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]

Parameters
  • [in] thread: Handle of the thread to wait for

cy_rslt_t cy_rtos_is_thread_running(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.

Return

The status of the thread running check. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]

Parameters
  • [in] thread: Handle of the terminated thread to delete

  • [out] running: Returns true if the thread is running, otherwise false

cy_rslt_t cy_rtos_get_thread_state(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.

Return

The status of the thread state check. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]

Parameters
  • [in] thread: Handle of the terminated thread to delete

  • [out] state: Returns the state the thread is currently in

cy_rslt_t cy_rtos_get_thread_handle(cy_thread_t *thread)

Get current thread handle.

Returns the unique thread handle of the current running thread.

Return

The status of thread join request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]

Parameters
  • [out] thread: Handle of the current running thread

Typedefs

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] arg: the argument passed from the thread create call to the entry function

Enums

enum cy_thread_state_t

cy_thread_state_t: The state a thread can be in.

Values:

enumerator CY_THREAD_STATE_INACTIVE

thread has not started or was terminated but not yet joined

enumerator CY_THREAD_STATE_READY

thread can run, but is not currently

enumerator CY_THREAD_STATE_RUNNING

thread is currently running

enumerator CY_THREAD_STATE_BLOCKED

thread is blocked waiting for something

enumerator CY_THREAD_STATE_TERMINATED

thread has terminated but not freed

enumerator CY_THREAD_STATE_UNKNOWN

thread is in an unknown state