miosix::Thread Class Reference
[Threads]

#include <kernel.h>

Collaboration diagram for miosix::Thread:

List of all members.

Public Member Functions

short int get_priority ()

void set_priority (short int pr)

void terminate ()

void wakeup ()

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)

static void yield ()

static void do_terminate ()

static bool test_terminate ()

static void sleep (unsigned int ms)

static Thread * get_current_thread ()

static bool exists (Thread *p)

static void wait ()

static Thread * IRQget_current_thread ()

static void IRQwait ()

static const int * get_stack_bottom ()

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

Thread * miosix::Thread::create	(	void()(void )	startfunc,
		unsigned int	stacksize,
		short int	priority = `1`,
		void *	argv = `NULL`
	)			`[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

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

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

void miosix::Thread::do_terminate ( ) [static]

Deprecated:: Called by a thread that wants to delete itself. This method does not return.
The idle thread will deallocate the thread resources. Another way for a thread to terminate is to just return from the thread's main function (entry point)
This method is deprecated and will be removed in future versions of the kernel. The reason why it is deprecated is that it can cause memory leaks. Consider this piece of code:

    void threadfunc(void *argv)
    {
        string s="Hello world";
        Thread::do_terminate();
    }

It leaks memory bcause the string destructor will never be called.
So, to terminate a thread the only safe way is to return from its main function.
CANNOT 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::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.

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.

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.

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.

void miosix::Thread::set_priority ( short int pr )

Set the priority of a thread.
To set the priority of the current thread use:

 Thread::get_current_thread()->set_priority(pr);

Parameters:

pr

desired priority. Must be 0<=pr<PRIORITY_MAX

Because of a bug it is not possible for a thread to call this method to set the priority of another thread. In this case the result is undefined (it may or may not set the priority) because it conflicts with the priority inheritance mechanism of mutexes. As a workaround create the thread with the desired priority using Thread::create() or change a thread's priority only from the thread itself.

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

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

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.

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.

    miosix_private::disable_interrupts();
    ...
    Thread::IRQwait();//Return immediately
    miosix_private::enable_interrupts();
    miosix::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.

const int * miosix::Thread::get_stack_bottom ( ) [static]

This is the lowest level method of the Thread class. It is only meant to implement functions to check the available stack in a thread.
Any other use is discouraged, since this method may change in future versions.
Returned pointer is constant because modifying the stack through it must be avoided.

Returns:: pointer to bottom of stack.

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:

/home/fede/Documents/Projects/ARM/miosix/miosix_np/miosix/kernel/kernel.h
/home/fede/Documents/Projects/ARM/miosix/miosix_np/miosix/kernel/kernel.cpp
/home/fede/Documents/Projects/ARM/miosix/miosix_np/miosix/kernel/portability.cpp


Public Member Functions
short int	get_priority ()
void	set_priority (short int pr)
void	terminate ()
void	wakeup ()
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)
static void	yield ()
static void	do_terminate ()
static bool	test_terminate ()
static void	sleep (unsigned int ms)
static Thread *	get_current_thread ()
static bool	exists (Thread *p)
static void	wait ()
static Thread *	IRQget_current_thread ()
static void	IRQwait ()
static const int *	get_stack_bottom ()
Friends
void	IRQfind_next_thread ()

miosix::Thread Class Reference [Threads]

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

Friends And Related Function Documentation

miosix::Thread Class Reference
[Threads]