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)

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

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

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

• stack[in] 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.

• stack_size[in] The size of the thread stack in bytes

• arg[in] The argument to pass to the new thread

Returns

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

cy_rslt_t cy_rtos_exit_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.

Returns

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

cy_rslt_t cy_rtos_terminate_thread(cy_thread_t *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

Returns

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

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.

Parameters

Returns

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

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.

Parameters

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

Returns

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

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.

Parameters

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

Returns

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

cy_rslt_t cy_rtos_get_thread_handle(cy_thread_t *thread)

Parameters

Returns

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

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

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

Enums

enum cy_thread_state_t

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

enumerator CY_THREAD_STATE_BLOCKED
enumerator CY_THREAD_STATE_TERMINATED
enumerator CY_THREAD_STATE_UNKNOWN