#include <kernel.h>

Collaboration diagram for miosix::Thread:

Public Types
enum	Options { DEFAULT =0, JOINABLE =1<<0 }

Public Member Functions
Priority	getPriority ()

void	terminate ()

void	wakeup ()

void	PKwakeup ()

void	detach ()

bool	isDetached () const

bool	join (void **result=NULL)

Priority	IRQgetPriority ()

void	IRQwakeup ()

Static Public Member Functions
static Thread *	create (void (startfunc)(void ), unsigned int stacksize, Priority priority=Priority(), void argv=NULL, unsigned short options=DEFAULT)

static Thread *	create (void(startfunc)(void ), unsigned int stacksize, Priority priority=Priority(), void *argv=NULL, unsigned short options=DEFAULT)

static void	yield ()

static bool	testTerminate ()

static void	sleep (unsigned int ms)

static void	sleepUntil (long long absoluteTime)

static Thread *	getCurrentThread ()

static bool	exists (Thread *p)

static void	setPriority (Priority pr)

static void	wait ()

static Thread *	IRQgetCurrentThread ()

static void	IRQwait ()

static bool	IRQexists (Thread *p)

Detailed Description

This class represents a thread. It has methods for creating, deleting and handling threads.
It has private constructor and destructor, since memory for a thread is handled by the kernel.
To create a thread use the static producer method create().
Methods that have an effect on the current thread, that is, the thread that is calling the method are static.
Calls to non static methods must be done with care, because a thread can terminate at any time. For example, if you call wakeup() on a terminated thread, the behavior is undefined.

Member Function Documentation

Thread * miosix::Thread::create	(	void ()(void *)	startfunc,
		unsigned int	stacksize,
		Priority	priority = `Priority()`,
		void *	argv = `NULL`,
		unsigned short	options = `DEFAULT`
	)

static

Producer method, creates a new thread.

Parameters

startfunc	the entry point function for the thread
stacksize	size of thread stack, its minimum is the constant STACK_MIN. The size of the stack must be divisible by 4, otherwise it will be rounded to a number divisible by 4.
priority	the thread's priority, between 0 (lower) and PRIORITY_MAX-1 (higher)
argv	a void* pointer that is passed as pararmeter to the entry point function
options	thread options, such ad Thread::JOINABLE

Returns: a reference to the thread created, that can be used, for example, to delete it, or NULL in case of errors.

Calls errorHandler(INVALID_PARAMETERS) if stacksize or priority are invalid. Can be called when the kernel is paused.

Thread * miosix::Thread::create	(	void()(void )	startfunc,
		unsigned int	stacksize,
		Priority	priority = `Priority()`,
		void *	argv = `NULL`,
		unsigned short	options = `DEFAULT`
	)

static

Same as create(void (startfunc)(void *), unsigned int stacksize, Priority priority=1, void *argv=NULL) but in this case the entry point of the thread returns a void

Parameters

startfunc	the entry point function for the thread
stacksize	size of thread stack, its minimum is the constant STACK_MIN. The size of the stack must be divisible by 4, otherwise it will be rounded to a number divisible by 4.
priority	the thread's priority, between 0 (lower) and PRIORITY_MAX-1 (higher)
argv	a void* pointer that is passed as pararmeter to the entry point function
options	thread options, such ad Thread::JOINABLE

Returns: a reference to the thread created, that can be used, for example, to delete it, or NULL in case of errors.

void miosix::Thread::detach ( )

Detach the thread if it was joinable, otherwise do nothing.
If called on a deleted joinable thread on which join was not yet called, it allows the thread's memory to be deallocated.
If called on a thread that is not yet deleted, the call detaches the thread without deleting it. If called on an already detached thread, it has undefined behaviour.

bool miosix::Thread::exists ( Thread * p )

static

Check if a thread exists

Parameters

p	thread to check

Returns: true if thread exists, false if does not exist or has been deleted. A joinable thread is considered existing until it has been joined, even if it returns from its entry point (unless it is detached and terminates).

Can be called when the kernel is paused.

Thread * miosix::Thread::getCurrentThread ( )

static

Return a pointer to the Thread class of the current thread.

Returns: a pointer to the current thread.

Can be called when the kernel is paused.

Priority miosix::Thread::getPriority ( )

Returns the priority of a thread.
To get the priority of the current thread use:

Thread::getCurrentThread()->getPriority();

If the thread is currently locking one or more mutexes, this member function returns the current priority, which can be higher than the original priority due to priority inheritance.

Returns: current priority of the thread

Can be called when the kernel is paused.

bool miosix::Thread::IRQexists ( Thread * p )

static

Same as exists() but is meant to be called only inside an IRQ or when interrupts are disabled.

Thread * miosix::Thread::IRQgetCurrentThread ( )

static

Same as get_current_thread(), but meant to be used insida an IRQ, when interrupts are disabled or when the kernel is paused.

Priority miosix::Thread::IRQgetPriority ( )

Same as getPriority(), but meant to be used inside an IRQ, when interrupts are disabled or when the kernel is paused.

void miosix::Thread::IRQwait ( )

static

Same as wait(), but is meant to be used only inside an IRQ or when interrupts are disabled.
Note: this method is meant to put the current thread in wait status in a piece of code where interrupts are disbled; it returns immediately, so the user is responsible for re-enabling interrupts and calling yield to effectively put the thread in wait status.

disableInterrupts();
...
Thread::IRQwait();//Return immediately
enableInterrupts();
Thread::yield();//After this, thread is in wait status

void miosix::Thread::IRQwakeup ( )

Same as wakeup(), but is meant to be used only inside an IRQ or when interrupts are disabled.

bool miosix::Thread::isDetached ( ) const

Returns: true if the thread is detached

bool miosix::Thread::join ( void ** result = NULL )

Wait until a joinable thread is terminated.
If the thread already terminated, this function returns immediately.
Calling join() on the same thread multiple times, from the same or multiple threads is not recomended, but in the current implementation the first call will wait for join, and the other will return false.
Trying to join the thread join is called in returns false, but must be avoided.
Calling join on a detached thread might cause undefined behaviour.

Parameters

result If the entry point function of the thread to join returns void *, the return value of the entry point is stored here, otherwise the content of this variable is undefined. If NULL is passed as result the return value will not be stored.

Returns: true on success, false on failure

void miosix::Thread::PKwakeup ( )

Wakeup a thread.
Can be called when the kernel is paused.

void miosix::Thread::setPriority ( Priority pr )

static

Set the priority of this thread.
This member function changed from previous Miosix versions since it is now static. This implies a thread can no longer set the priority of another thread.

Parameters

pr	desired priority. Must be 0<=pr<PRIORITY_MAX

Calls errorHandler(INVALID_PARAMETERS) if pr is not within bounds.

Can be called when the kernel is paused.

void miosix::Thread::sleep ( unsigned int ms )

static

Put the thread to sleep for a number of milliseconds.
The actual precision depends on the kernel tick used. If the specified wait time is lower than the tick accuracy, the thread will be put to sleep for one tick.
Maximum sleep time is (2^32-1) / TICK_FREQ. If a sleep time higher than that value is specified, the behaviour is undefined.

Parameters

ms	the number of millisecond. If it is ==0 this method will return immediately

CANNOT be called when the kernel is paused.

void miosix::Thread::sleepUntil ( long long absoluteTime )

static

Put the thread to sleep until the specified absolute time is reached. If the time is in the past, returns immediately. To make a periodic thread, this is the recomended way

void periodicThread()
{
    //Run every 90 milliseconds
    const int period=static_cast<int>(TICK_FREQ*0.09);
    long long tick=getTick();
    for(;;)
    {
        //Do work
        tick+=period;
        Thread::sleepUntil(tick);
    }
}

Parameters

absoluteTime when to wake up

CANNOT be called when the kernel is paused.

void miosix::Thread::terminate ( )

Suggests a thread to terminate itself. Note that this method only makes testTerminate() return true on the specified thread. If the thread does not call testTerminate(), or if it calls it but does not delete itself by returning from entry point function, it will NEVER terminate. The user is responsible for implementing correctly this functionality.
Thread termination is implemented like this to give time to a thread to deallocate resources, close files... before terminating.
Can be called when the kernel is paused.

bool miosix::Thread::testTerminate ( )

static

This method needs to be called periodically inside the thread's main loop.

Returns: true if somebody outside the thread called terminate() on this thread.

If it returns true the thread must free all resources and terminate by returning from its main function.
Can be called when the kernel is paused.

void miosix::Thread::wait ( )

static

This method stops the thread until another thread calls wakeup() on this thread.
Calls to wait are not cumulative. If wait() is called two times, only one call to wakeup() is needed to wake the thread.
CANNOT be called when the kernel is paused.

void miosix::Thread::wakeup ( )

Wakeup a thread.
CANNOT be called when the kernel is paused.

void miosix::Thread::yield ( )

static

When called, suggests the kernel to pause the current thread, and run another one.
CANNOT be called when the kernel is paused.

The documentation for this class was generated from the following files:

kernel.h
kernel.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation