Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages   Examples  

Thread Management

Coperative multi-threading support. More...


Modules

Thread States
 Thread operating states.


Data Structures

struct  _NUTTHREADINFO
 Thread information structure. More...

struct  _NUTTHREADINFO
 Thread information structure. More...

struct  ENTERFRAME
struct  SWITCHFRAME

Typedefs

typedef struct _NUTTHREADINFO NUTTHREADINFO

Functions

void NutThreadSwitch (void)
 Switch to another thread. More...

void NutThreadAddPriQueue (NUTTHREADINFO *td, NUTTHREADINFO *volatile *tqpp)
 Add a thread to a prioritiy ordered queue. More...

void NutThreadRemoveQueue (NUTTHREADINFO *td, NUTTHREADINFO *volatile *tqpp)
 Remove a thread from a specified queue. More...

void NutThreadResumeAsync (HANDLE th)
 Make a previously suspended thread ready to run. More...

void NutThreadResume (HANDLE th)
 Resume a previously suspended thread. More...

void NutThreadWake (HANDLE timer, HANDLE th)
 Resume a previously suspended thread. More...

void NutThreadSuspend (HANDLE *thp)
 Suspend the running thread. More...

void NutThreadYield (void)
 Give up the CPU. More...

u_char NutThreadSetPriority (u_char level)
 Set the current thread's priority. More...

HANDLE NutThreadCreate (u_char *name, void(*fn)(void *), void *arg, u_short stackSize)
 Create a new thread. More...


Variables

NUTTHREADINFOrunningThread
 Currently running thread. More...

NUTTHREADINFO* volatile nutThreadList
NUTTHREADINFO* volatile runQueue
 List of ready-to-run threads. More...


Detailed Description

Coperative multi-threading support.

Typically Nut/OS is at its most useful where there are several concurrent tasks that need to be undertaken at the same time. To support this requirement, Nut/OS offers some kind of light processes called threads. In this context a thread is a sequence of executing software that can be considered to be logically independent from other software that is running on the same CPU.

All threads are executing in the same address space using the same hardware resources, which significantly reduces task switching overhead. Therefore it is important to stop them from causing each other problems. This is particularly an issue where two or more threads need to share a resources like memory locations or peripheral devices.

The system works on the principle that the most urgent thread always runs. One exception to this is if a CPU interrupt arrives and the interrupt has not been disabled. Each thread has a priority which is used to determine how urgent it is. This priority ranges from 0 to 255, with the lowest value indicating the most urgent.

Nut/OS implements cooperative multithreading. That means, that threads are not bound to a fixed timeslice. Unless they are waiting for specific event or explicitely yielding the CPU, they can rely on not being stopped unexpectedly. However, they may be interrupted by hardware interrupt signals. In opposite to pre-emptive multithreading, coorperative multithreading simplifies resource sharing and results in faster and smaller code.

Version:
2.0.4
Author:
Harald Kipp, egnite Software GmbH

Typedef Documentation

typedef struct _NUTTHREADINFO NUTTHREADINFO
 

Thread information structure type.


Function Documentation

void NutThreadAddPriQueue ( NUTTHREADINFO * td,
NUTTHREADINFO *volatile * tqpp )
 

Add a thread to a prioritiy ordered queue.

Insert the thread into a specified queue behind the last thread with lower or equal priority.

CPU interrupts must have been disabled before calling this function.

Parameters:
td   Pointer to NUTTHREADINFO of the thread to be inserted in the queue.
tqpp   Pointer to the root of the queue.

HANDLE NutThreadCreate ( u_char * name,
void(* fn)(void *),
void * arg,
u_short stackSize )
 

Create a new thread.

If the current thread's priority is lower or equal than the default priority (64), then the current thread is stopped and the new one is started.

Note:
Interrupts are automatically enabled when this function returns.
Parameters:
name   String containing the symbolic name of the new thread, up to 8 characters long.
fn   The thread's entry point, typically created by the THREAD macro.
arg   Argument pointer passed to the new thread.
stackSize   Number of bytes of the stack space allocated for the new thread.
Examples:
portdio/portdio.c, and threads/threads.c.

void NutThreadRemoveQueue ( NUTTHREADINFO * td,
NUTTHREADINFO *volatile * tqpp )
 

Remove a thread from a specified queue.

CPU interrupts must have been disabled before calling this function.

Parameters:
td   Pointer to NUTTHREADINFO of the thread to be removed from the queue.
tqpp   Pointer to the root of the queue.

void NutThreadResume ( HANDLE th )
 

Resume a previously suspended thread.

Note:
Interrupts are automatically enabled when this function returns.

void NutThreadResumeAsync ( HANDLE th )
 

Make a previously suspended thread ready to run.

Note:
CPU interrupts must have been disabled before calling this function. It is save to call this function from within an interrupt handler.

u_char NutThreadSetPriority ( u_char level )
 

Set the current thread's priority.

The priority of newly created threads is set to 64, but may be changed when the thread starts running.

When another thread with a higher or equal priority is ready to run, the current thread will be stopped and control of the CPU is passed to the other thread.

The function returns the old priority, which makes it easy to temporarily switch to another priority and later set back the old one.

Note:
Interrupts are automatically enabled when this function returns.
Parameters:
level   New priority level.

Returns:
The old priority of this thread.
Examples:
threads/threads.c.

void NutThreadSuspend ( HANDLE * thp )
 

Suspend the running thread.

Note:
Interrupts are automatically enabled when this function returns.

void NutThreadSwitch ( void )
 

Switch to another thread.

Stop the current thread, saving its context. Then start the one with the highest priority, which is ready to run.

Application programs typically do not call this function.

CPU interrupts must be disabled before calling this function.

void NutThreadWake ( HANDLE timer,
HANDLE th )
 

Resume a previously suspended thread.

Applications typically do not call this function.

void NutThreadYield ( void )
 

Give up the CPU.

If another thread within the same or higher priority is ready to run, then the current thread is stopped and the other one is started.

Note:
Interrupts are automatically enabled when this function returns.
Examples:
portdio/portdio.c.


Variable Documentation

NUTTHREADINFO *volatile runQueue
 

List of ready-to-run threads.

Priority ordered linked list of NUTTHREADINFO structures of all threads which are ready to run.

NUTTHREADINFO * runningThread
 

Currently running thread.

Pointer to the NUTTHREADINFO structure of the currently running thread.


© 2000-2001 by egnite Software GmbH - visit http://www.ethernut.de/