Cooperative multithreading system. More...

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

Macros
#define	COTHREAD_DETACHED (1 << 0)
	Flags a thread as detached.

Typedefs
typedef int	comutex_t
	Mutex.

typedef int(*	cothread_entrypoint_t) (void *)
	Thread entrypoint.

typedef int	cothread_t
	Thread ID.

Functions
static void	comutex_acquire (comutex_t *mutex)
	Waits in a loop until the mutex is available.

static bool	comutex_init (comutex_t *mutex)
	Initializes a mutex.

static void	comutex_release (comutex_t *mutex)
	Releases a mutex.

static bool	comutex_try_acquire (comutex_t *mutex)
	Tries to acquire a mutex without blocking execution.

cothread_t	cothread_create (cothread_entrypoint_t entrypoint, void *arg, size_t stack_size, unsigned int flags)
	Creates a thread and allocate the stack for it.

cothread_t	cothread_create_manual (cothread_entrypoint_t entrypoint, void arg, void stack_base, size_t stack_size, unsigned int flags)
	Create a thread.

int	cothread_delete (cothread_t thread)
	Deletes a running thread and frees all memory used by it.

int	cothread_detach (cothread_t thread)
	Detach the specified thread.

cothread_t	cothread_get_current (void)
	Returns ID of the thread that is running currently.

int	cothread_get_exit_code (cothread_t thread)
	If the thread has ended, this function returns the exit code.

bool	cothread_has_joined (cothread_t thread)
	Used to determine if a thread is running or if it has ended (joined).

void	cothread_yield (void)
	Tells the scheduler to switch to a different thread.

void	cothread_yield_irq (uint32_t flags)
	Tells the scheduler to switch to a different thread until the specified IRQ has happened.

void	cothread_yield_irq_aux (uint32_t flags)
	Tells the scheduler to switch to a different thread until the specified ARM7 AUX IRQ has happened.

Detailed Description

Cooperative multithreading system.

Only enabled in the ARM9 at the moment.

Macro Definition Documentation

◆ COTHREAD_DETACHED

#define COTHREAD_DETACHED (1 << 0)

Flags a thread as detached.

A detached thread deallocates all memory used by it when it ends. Calling cothread_has_joined() or cothread_get_exit_code() isn't allowed.

Function Documentation

◆ comutex_acquire()

static void comutex_acquire ( comutex_t * mutex )

inlinestatic

Waits in a loop until the mutex is available.

The main body of the loop calls cothread_yield() after each try, so that other threads can take control of the CPU and eventually release the mutex.

Parameters

mutex Pointer to the mutex.

◆ comutex_init()

static bool comutex_init ( comutex_t * mutex )

inlinestatic

Initializes a mutex.

Parameters

mutex Pointer to the mutex.

Returns: It returns true if the mutex has been initialized, false if not.

◆ comutex_release()

static void comutex_release ( comutex_t * mutex )

inlinestatic

Releases a mutex.

Parameters

mutex Pointer to the mutex.

◆ comutex_try_acquire()

static bool comutex_try_acquire ( comutex_t * mutex )

inlinestatic

Tries to acquire a mutex without blocking execution.

Parameters

mutex Pointer to the mutex.

Returns: It returns true if the mutex has been acquired, false if not.

◆ cothread_create()

cothread_t cothread_create	(	cothread_entrypoint_t	entrypoint,
		void *	arg,
		size_t	stack_size,
		unsigned int	flags
	)

Creates a thread and allocate the stack for it.

This stack will be freed when the thread is deleted.

Important: If this thread is going to do filesystem accesses, you need to assign it a reasonably big stack size.

Parameters

entrypoint	Function to be run. The argument is the value of 'arg' passed to cothread_create().
arg	Argument to be passed to entrypoint.
stack_size	Size of the stack. If it is set to zero it will use a default value. If non-zero, it must be aligned to 64 bit.
flags	Set of ORed flags (like COTHREAD_DETACHED) or 0.

Returns: On success, it returns a non-negative value representing the thread ID. On failure, it returns -1 and sets errno.

◆ cothread_create_manual()

cothread_t cothread_create_manual	(	cothread_entrypoint_t	entrypoint,
		void *	arg,
		void *	stack_base,
		size_t	stack_size,
		unsigned int	flags
	)

Create a thread.

The stack is owned by the caller of this function, and it has to be freed manually after the thread ends.

Parameters

entrypoint	Function to be run. The argument is the value of 'arg' passed to cothread_create_manual().
arg	Argument to be passed to entrypoint.
stack_base	Pointer to the base of the memory to be used as stack. It must be aligned to 64 bit.
stack_size	Size of the stack. Must be aligned to 64 bit.
flags	Set of ORed flags (like COTHREAD_DETACHED) or 0.

Returns: On success, it returns a non-negative value representing the thread ID. On failure, it returns -1 and sets errno.

◆ cothread_delete()

int cothread_delete ( cothread_t thread )

Deletes a running thread and frees all memory used by it.

It isn't possible to delete the currently running thread.

Parameters

thread Thread ID.

Returns: On success, it returns 0. On failure, it returns -1 and sets errno.

◆ cothread_detach()

int cothread_detach ( cothread_t thread )

Detach the specified thread.

Parameters

thread The thread to detach.

Returns: On success, it returns 0. On failure, it returns -1 and sets errno.

◆ cothread_get_current()

cothread_t cothread_get_current ( void )

Returns ID of the thread that is running currently.

Returns: Thread ID of the current thread.

◆ cothread_get_exit_code()

int cothread_get_exit_code ( cothread_t thread )

If the thread has ended, this function returns the exit code.

Don't call this if the thread is detached, it will never return an exit code because the thread information will be deleted as soon as the thread ends (and, at that point, it won't exist, so the function will return an error code).

Parameters

thread Thread ID.

Returns: Returns the exit code if the thread has finished, -1 otherwise. It will set errno as well (for example, if the thread is still running, it will set errno to EBUSY).

◆ cothread_has_joined()

bool cothread_has_joined ( cothread_t thread )

Used to determine if a thread is running or if it has ended (joined).

Don't call this if the thread is detached. It will always return false because as soon as the thread ends all information associated to it will be deleted (and, at that point, it won't exist, so the function will return false along an error code).

Parameters

thread Thread ID.

Returns: Returns true if the thread has ended, false otherwise. It can also set errno.

◆ cothread_yield()

void cothread_yield ( void )

Tells the scheduler to switch to a different thread.

This can also be called from main().

◆ cothread_yield_irq()

void cothread_yield_irq ( uint32_t flags )

Tells the scheduler to switch to a different thread until the specified IRQ has happened.

Parameters

flags IRQ flags to wait for.

◆ cothread_yield_irq_aux()

void cothread_yield_irq_aux ( uint32_t flags )

Tells the scheduler to switch to a different thread until the specified ARM7 AUX IRQ has happened.

Parameters

flags AUX IRQ flags to wait for.

Note: ARM7 only.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ COTHREAD_DETACHED

Function Documentation

◆ comutex_acquire()

◆ comutex_init()

◆ comutex_release()

◆ comutex_try_acquire()

◆ cothread_create()

◆ cothread_create_manual()

◆ cothread_delete()

◆ cothread_detach()

◆ cothread_get_current()

◆ cothread_get_exit_code()

◆ cothread_has_joined()

◆ cothread_yield()

◆ cothread_yield_irq()

◆ cothread_yield_irq_aux()