Miosix  2.0alpha1
miosix::Thread Class Reference

#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 Threadcreate (void *(*startfunc)(void *), unsigned int stacksize, Priority priority=Priority(), void *argv=NULL, unsigned short options=DEFAULT)
 
static Threadcreate (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 ThreadgetCurrentThread ()
 
static bool exists (Thread *p)
 
static void setPriority (Priority pr)
 
static void wait ()
 
static ThreadIRQgetCurrentThread ()
 
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
startfuncthe entry point function for the thread
stacksizesize 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.
prioritythe thread's priority, between 0 (lower) and PRIORITY_MAX-1 (higher)
argva void* pointer that is passed as pararmeter to the entry point function
optionsthread 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
startfuncthe entry point function for the thread
stacksizesize 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.
prioritythe thread's priority, between 0 (lower) and PRIORITY_MAX-1 (higher)
argva void* pointer that is passed as pararmeter to the entry point function
optionsthread 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
pthread 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:

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.

...
Thread::IRQwait();//Return immediately
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
resultIf 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
prdesired 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
msthe 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;
}
}
Parameters
absoluteTimewhen 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: