General Description

APIs for creating and working with Threads.

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. More...

Enumerations
enum	cy_thread_state_t { CY_THREAD_STATE_INACTIVE , CY_THREAD_STATE_READY , CY_THREAD_STATE_RUNNING , CY_THREAD_STATE_BLOCKED , CY_THREAD_STATE_TERMINATED , CY_THREAD_STATE_UNKNOWN }
	The state a thread can be in. More...

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. More...

cy_rslt_t	cy_rtos_thread_exit (void)
	Exit the current thread. More...

cy_rslt_t	cy_rtos_thread_terminate (cy_thread_t *thread)
	Terminates another thread. More...

cy_rslt_t	cy_rtos_thread_join (cy_thread_t *thread)
	Waits for a thread to complete. More...

cy_rslt_t	cy_rtos_thread_is_running (cy_thread_t thread, bool running)
	Checks if the thread is running. More...

cy_rslt_t	cy_rtos_thread_get_state (cy_thread_t thread, cy_thread_state_t state)
	Gets the state the thread is currently in. More...

cy_rslt_t	cy_rtos_thread_get_handle (cy_thread_t *thread)
	Get current thread handle. More...

cy_rslt_t	cy_rtos_thread_wait_notification (cy_time_t timeout_ms)
	Suspend current thread until notification is received. More...

cy_rslt_t	cy_rtos_thread_set_notification (cy_thread_t *thread)
	Set the thread notification for a thread. More...

cy_rslt_t	cy_rtos_thread_get_name (cy_thread_t thread, const char *thread_name)
	Get the name of a thread. More...

#define	cy_rtos_create_thread(thread, entry_function, name, stack, stack_size, priority, arg) cy_rtos_thread_create(thread, entry_function, name, stack, stack_size, priority, arg)
	Create a thread with specific thread argument. More...

#define	cy_rtos_is_thread_running(thread, running) cy_rtos_thread_is_running(thread, running)
	Checks if the thread is running. More...

#define	cy_rtos_set_thread_notification(thread, in_isr) cy_rtos_thread_set_notification(thread)
	Set the thread notification for a thread. More...

#define	cy_rtos_wait_thread_notification(timeout_ms) cy_rtos_thread_wait_notification(timeout_ms)
	Suspend current thread until notification is received. More...

#define	cy_rtos_get_thread_state(thread, state) cy_rtos_thread_get_state(thread, state)
	Gets the state the thread is currently in. More...

#define	cy_rtos_join_thread(thread) cy_rtos_thread_join(thread)
	Waits for a thread to complete. More...

#define	cy_rtos_get_thread_handle(thread) cy_rtos_thread_get_handle(thread)
	Get current thread handle. More...

#define	cy_rtos_terminate_thread(thread) cy_rtos_thread_terminate(thread)
	Terminates another thread. More...

#define	cy_rtos_exit_thread cy_rtos_thread_exit
	Exit the current thread. More...

Macro Definition Documentation

◆ cy_rtos_create_thread

#define cy_rtos_create_thread	(	thread,
		entry_function,
		name,
		stack,
		stack_size,
		priority,
		arg
	)	cy_rtos_thread_create(thread, entry_function, name, stack, stack_size, priority, 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]	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

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

◆ cy_rtos_is_thread_running

#define cy_rtos_is_thread_running	(	thread,
		running
	)	cy_rtos_thread_is_running(thread, 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]	thread	Handle of the terminated thread to delete
[out]	running	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_rtos_set_thread_notification

#define cy_rtos_set_thread_notification	(	thread,
		in_isr
	)	cy_rtos_thread_set_notification(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]	thread	Handle of the target thread
[in]	in_isr	If true this is being called from within an ISR

Returns: The status of thread wait. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR, CY_RTOS_BAD_PARAM]

◆ cy_rtos_wait_thread_notification

#define cy_rtos_wait_thread_notification ( timeout_ms ) cy_rtos_thread_wait_notification(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_ms Maximum number of milliseconds to wait Use the CY_RTOS_NEVER_TIMEOUT constant to wait forever.

Returns: The status of thread wait. [CY_RSLT_SUCCESS, CY_RTOS_TIMEOUT, CY_RTOS_GENERAL_ERROR]

◆ cy_rtos_get_thread_state

#define cy_rtos_get_thread_state	(	thread,
		state
	)	cy_rtos_thread_get_state(thread, 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]	thread	Handle of the terminated thread to delete
[out]	state	Returns the state the thread is currently in

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

◆ cy_rtos_join_thread

#define cy_rtos_join_thread ( thread ) cy_rtos_thread_join(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] thread Handle of the thread to wait for

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

◆ cy_rtos_get_thread_handle

#define cy_rtos_get_thread_handle ( thread ) cy_rtos_thread_get_handle(thread)

Get current thread handle.

Returns the unique thread handle of the current running thread.

Parameters

[out] thread Handle of the current running thread

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

◆ cy_rtos_terminate_thread

#define cy_rtos_terminate_thread ( thread ) cy_rtos_thread_terminate(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] thread Handle of the thread to terminate

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

◆ 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 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]

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

Enumeration Type Documentation

◆ cy_thread_state_t

enum cy_thread_state_t

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

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]	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

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

◆ 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 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_thread_join) to ensure their resources are fully cleaned up.

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

◆ cy_rtos_thread_terminate()

cy_rslt_t cy_rtos_thread_terminate ( 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] thread Handle of the thread to terminate

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

◆ 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] thread Handle of the thread to wait for

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

◆ cy_rtos_thread_is_running()

cy_rslt_t cy_rtos_thread_is_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_thread_get_state() function.

Parameters

[in]	thread	Handle of the terminated thread to delete
[out]	running	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_rtos_thread_get_state()

cy_rslt_t cy_rtos_thread_get_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

[in]	thread	Handle of the terminated thread to delete
[out]	state	Returns the state the thread is currently in

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

◆ 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] thread Handle of the current running thread

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

◆ 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_ms Maximum number of milliseconds to wait Use the CY_RTOS_NEVER_TIMEOUT constant to wait forever.

Returns: The status of thread wait. [CY_RSLT_SUCCESS, CY_RTOS_TIMEOUT, CY_RTOS_GENERAL_ERROR]

◆ cy_rtos_thread_set_notification()

cy_rslt_t cy_rtos_thread_set_notification ( 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] thread Handle of the target thread

Returns: The status of thread wait. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR, CY_RTOS_BAD_PARAM]

◆ cy_rtos_thread_get_name()

cy_rslt_t cy_rtos_thread_get_name	(	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]	thread	Handle of the target thread
[out]	thread_name	Will 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. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]

General Description

Typedefs

Enumerations

Macro Definition Documentation

◆ cy_rtos_create_thread

◆ cy_rtos_is_thread_running

◆ cy_rtos_set_thread_notification

◆ cy_rtos_wait_thread_notification

◆ cy_rtos_get_thread_state

◆ cy_rtos_join_thread

◆ cy_rtos_get_thread_handle

◆ cy_rtos_terminate_thread

◆ cy_rtos_exit_thread

Typedef Documentation

◆ cy_thread_entry_fn_t

Enumeration Type Documentation

◆ cy_thread_state_t

Function Documentation

◆ cy_rtos_thread_create()

◆ cy_rtos_thread_exit()

◆ cy_rtos_thread_terminate()

◆ cy_rtos_thread_join()

◆ cy_rtos_thread_is_running()

◆ cy_rtos_thread_get_state()

◆ cy_rtos_thread_get_handle()

◆ cy_rtos_thread_wait_notification()

◆ cy_rtos_thread_set_notification()

◆ cy_rtos_thread_get_name()