miosix::Thread Class Reference
[Kernel]

#include <kernel.h>

Collaboration diagram for miosix::Thread:

List of all members.

Public Types

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

Public Member Functions

short int get_priority ()

void terminate ()

void wakeup ()

void detach ()

bool isDetached () const

bool join (void **result=NULL)

short int IRQget_priority ()

void IRQwakeup ()

Static Public Member Functions

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

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

static void yield ()

static bool test_terminate ()

static void sleep (unsigned int ms)

static Thread * get_current_thread ()

static bool exists (Thread *p)

static void set_priority (short int pr)

static void wait ()

static Thread * IRQget_current_thread ()

static void IRQwait ()

static bool IRQexists (Thread *p)

Friends

void IRQfind_next_thread ()

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 Enumeration Documentation

enum miosix::Thread::Options

Thread options, can be passed to Thread::create to set additional options of the thread. More options can be specified simultaneously by ORing them together. The DEFAULT option indicates the default thread creation.

Enumerator:

DEFAULT	Default thread options.
JOINABLE	Thread is joinable instead of detached.

Member Function Documentation

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

Same as create(void (*startfunc)(void *), unsigned int stacksize, short int 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.

Thread * miosix::Thread::create	(	void ()(void *)	startfunc,
		unsigned int	stacksize,
		short int	priority = `1`,
		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 error_handler(INVALID_PARAMETERS) if stacksize or priority are invalid, and error_handler(OUT_OF_MEMORY) if the heap is full. Can be called when the kernel is paused. Note: this is the only method of this class that can be called BEFORE the kernel is started.

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::get_current_thread ( ) [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.

short int miosix::Thread::get_priority ( )

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

 Thread::get_current_thread()->get_priority();

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::IRQget_current_thread ( ) [static]

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

short int miosix::Thread::IRQget_priority ( )

Same as get_priority(), 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.

 disable_interrupts();
 ...
 Thread::IRQwait();//Return immediately
 enable_interrupts();
 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::set_priority ( short int 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 error_handler(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::terminate ( )

Suggests a thread to terminate itself. Note that this method only makes test_terminate() return true on the specified thread. If the thread does not call test_terminate(), 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::test_terminate ( ) [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.
Can 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.

Friends And Related Function Documentation

void IRQfind_next_thread ( ) [friend]

This function is used to developed interrupt driven peripheral drivers.
Can be used ONLY inside an IRQ (and not when interrupts are disabled) to find next thread in READY status. If the kernel is paused, does nothing. Can be used for example if an IRQ causes a higher priority thread to be woken, to change context. Note that to use this function the IRQ must use the macros to save/restore context defined in portability.h

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

/Users/fede/Documents/Projects/ARM/miosix/miosix_np_2/miosix/kernel/kernel.h
/Users/fede/Documents/Projects/ARM/miosix/miosix_np_2/miosix/kernel/kernel.cpp


Public Types
enum	Options { DEFAULT = 0, JOINABLE = 1<<0 }
Public Member Functions
short int	get_priority ()
void	terminate ()
void	wakeup ()
void	detach ()
bool	isDetached () const
bool	join (void **result=NULL)
short int	IRQget_priority ()
void	IRQwakeup ()
Static Public Member Functions
static Thread *	create (void (startfunc)(void ), unsigned int stacksize, short int priority=1, void argv=NULL, unsigned short options=DEFAULT)
static Thread *	create (void(startfunc)(void ), unsigned int stacksize, short int priority=1, void *argv=NULL, unsigned short options=DEFAULT)
static void	yield ()
static bool	test_terminate ()
static void	sleep (unsigned int ms)
static Thread *	get_current_thread ()
static bool	exists (Thread *p)
static void	set_priority (short int pr)
static void	wait ()
static Thread *	IRQget_current_thread ()
static void	IRQwait ()
static bool	IRQexists (Thread *p)
Friends
void	IRQfind_next_thread ()

miosix::Thread Class Reference [Kernel]

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Friends And Related Function Documentation

miosix::Thread Class Reference
[Kernel]