Threads

A k_thread whose stack comes from a pool and outlives it. More...

Files
file	mpipe_thread.h
	Simple wrapper of k_thread to reuse a thread's stack after its termination.

Data Structures
struct	mpipe_thread
	Simple wrapper around k_thread. More...

Enumerations
enum	mpipe_thread_state { MPIPE_THREAD_PAUSED = 0 , MPIPE_THREAD_RUNNING , MPIPE_THREAD_TERMINATED }
	Thread state. More...

Functions
k_tid_t	mpipe_thread_create (struct mpipe_thread *thread, k_thread_entry_t func, void *p1, void *p2, void *p3, int priority, k_timeout_t delay)
	Create a new thread reusing the stack from the thread pool.
int	mpipe_thread_wait (struct mpipe_thread *thread)
	Block the thread until it is allowed to run or must exit.
void	mpipe_thread_resume (struct mpipe_thread *thread)
	Resume a paused thread.
void	mpipe_thread_pause (struct mpipe_thread *thread)
	Pause a running thread.
int	mpipe_thread_join (struct mpipe_thread *thread, k_timeout_t timeout)
	Join a thread and release its stack back to the thread stack pool.

Detailed Description

A k_thread whose stack comes from a pool and outlives it.

A pipeline creates and destroys threads as it starts and stops, and a k_thread stack cannot simply be freed and reallocated on a system with no heap. This wrapper draws stacks from a fixed pool sized by CONFIG_MPIPE_THREADS_NUM, so a stack is returned when its thread terminates and reused by the next one.

Threads are created sleeping and started explicitly, which is what lets a pipeline build its whole graph before anything runs. mpipe_thread_wait is the loop's cooperation point: it blocks while paused and reports when a join has been requested, which is how a source loop learns to exit rather than being killed underneath itself.

Enumeration Type Documentation

mpipe_thread_state

enum mpipe_thread_state

#include <mpipe_thread.h>

Thread state.

Enumerator
MPIPE_THREAD_PAUSED	Thread is paused and can be resumed.
MPIPE_THREAD_RUNNING	Thread is running.
MPIPE_THREAD_TERMINATED	Thread is terminated.

Function Documentation

mpipe_thread_create()

k_tid_t mpipe_thread_create	(	struct mpipe_thread *	thread,
		k_thread_entry_t	func,
		void *	p1,
		void *	p2,
		void *	p3,
		int	priority,
		k_timeout_t	delay )

#include <mpipe_thread.h>

Create a new thread reusing the stack from the thread pool.

The thread is created in a sleeping state (K_FOREVER delay). Call mpipe_thread_resume() to actually start execution.

Parameters

thread	Pointer to an uninitialized struct Threads
func	Entry function of the thread
p1	First parameter to pass to the thread entry function
p2	Second parameter to pass to the thread entry function
p3	Third parameter to pass to the thread entry function
priority	Priority of the thread
delay	Scheduling delay, or K_NO_WAIT

Returns

ID of the newly created thread on success or NULL on failure

mpipe_thread_join()

int mpipe_thread_join	(	struct mpipe_thread *	thread,
		k_timeout_t	timeout )

#include <mpipe_thread.h>

Join a thread and release its stack back to the thread stack pool.

Signals the thread to exit, waits for it to terminate, and releases the stack back to the pool. If the thread was never woken, it is woken so it can observe the termination request and exit.

Parameters

thread	Pointer to a struct Threads to join
timeout	Maximum time to wait for the thread to join

Returns

0 on success or a negative errno on failure

mpipe_thread_pause()

void mpipe_thread_pause

(

struct mpipe_thread *

thread

)

#include <mpipe_thread.h>

Pause a running thread.

The thread will block at its next call to mpipe_thread_wait().

Parameters

thread

Pointer to a struct Threads to pause

mpipe_thread_resume()

void mpipe_thread_resume

(

struct mpipe_thread *

thread

)

#include <mpipe_thread.h>

Resume a paused thread.

Parameters

thread

Pointer to a struct Threads to resume

mpipe_thread_wait()

int mpipe_thread_wait

(

struct mpipe_thread *

thread

)

#include <mpipe_thread.h>

Block the thread until it is allowed to run or must exit.

Thread entry functions should call this at the top of their processing loop. The function blocks while the thread is paused and returns immediately when running.

Parameters

thread

Pointer to a struct Threads

Return values

0	Thread should proceed (running).
-ECANCELED	Thread must exit (join requested).