Thread Management
[Nut/OS API]

Cooperative multi-threading support. More...

Collaboration diagram for Thread Management:

Data Structures

struct  NUTTHREADINFO
 Thread information structure. More...

Functions

void NutThreadAddPriQueue (NUTTHREADINFO *td, NUTTHREADINFO *volatile *tqpp)
 Add a thread to a prioritiy ordered queue.
void NutThreadRemoveQueue (NUTTHREADINFO *td, NUTTHREADINFO *volatile *tqpp)
 Remove a thread from a specified queue.
void NutThreadResume (void)
 Continue with the highest priority thread, which is ready to run.
void NutThreadWake (HANDLE timer, HANDLE th)
 Resume a previously suspended thread.
void NutThreadYield (void)
 Give up the CPU.
uint8_t NutThreadSetPriority (uint8_t level)
 Set the current thread's priority.
void NutThreadExit (void)
 End the current thread.
void NutThreadDestroy (void)
 Free a thread that was previously killed and release memory back to the OS.
void NutThreadKill (void)
 Kill the running thread.
HANDLE GetThreadByName (char *name)
 Query handle of a thread with a specific name.

Variables

NUTTHREADINFO * runningThread
 Currently running thread.
NUTTHREADINFO * killedThread
 Thread to be killed.
NUTTHREADINFO * nutThreadList
 List of all created threads.
NUTTHREADINFO * runQueue
 List of ready-to-run threads.

Detailed Description

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

Todo:
Using the special priority 255 to kill a thread is not required and should be removed.

To specify a function named Back as an independant thread, one can write

 #include <sys/thread.h>

 THREAD(Back, arg)
 {
     for (;;) {
         NutSleep(1000);
     }
 } 

To start this thread, use

 #include <sys/thread.h>

 /* Other code here... */

 NutThreadCreate("Bg", Back, NULL, 512);
 /* Execution continues here and concurrently in the background thread.

The functions listed below are hardware independant. Additional API calls are located in the architecture dependant sections.


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.

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

Definition at line 287 of file thread.c.

References NUTASSERT, NutEnterCritical, NutExitCritical, and SIGNALED.

Referenced by NutEventPostAsync(), NutEventTimeout(), NutEventWait(), NutThreadCreate(), NutThreadSetPriority(), NutThreadWake(), and NutThreadYield().

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

Remove a thread from a specified queue.

Note:
Depending on the given 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.

Definition at line 339 of file thread.c.

References NutEnterCritical, NutExitCritical, and SIGNALED.

Referenced by NutEventWait(), NutSleep(), NutThreadSetPriority(), and NutThreadYield().

void NutThreadResume ( void   ) 

Continue with the highest priority thread, which is ready to run.

If the currently running thread lost its top position in the queue of ready-to-run threads, then the context will be switched.

Todo:
Removing a single thread from a wait queue only improves context switching, but may result in an event time-out for remaining threads, although events had been posted already.

Definition at line 380 of file thread.c.

References NutEnterCritical, NutEventPostAsync(), NutExitCritical, nutThreadList, NutThreadSwitch(), NutTimerProcessElapsed(), runningThread, runQueue, SIGNALED, TDS_READY, TDS_RUNNING, TRACE_ADD_ITEM, and TRACE_TAG_THREAD_YIELD.

Referenced by NutEventWait(), NutSleep(), and NutThreadYield().

void NutThreadWake ( HANDLE  timer,
HANDLE  th 
)

Resume a previously suspended thread.

This routine is called by the system when a sleep timer elapses.

Note:
This routine is used as a timer callback for NutSleep implementation Applications typically do not call this function.
Parameters:
timer Handle of the elapsed timer.
th Handle of the thread to wake up.
Todo:
Used by the timer module. Should be moved there, because not all applications will use of NutSleep().

Definition at line 448 of file thread.c.

References NUTASSERT, NutThreadAddPriQueue(), runQueue, and TDS_READY.

Referenced by NutDumpTimerList(), and NutSleep().

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.

Definition at line 466 of file thread.c.

References NutEnterCritical, NutExitCritical, NutThreadAddPriQueue(), NutThreadRemoveQueue(), NutThreadResume(), NutUnixThreadYieldHook(), runningThread, and runQueue.

Referenced by dxm2usb(), NutEventBroadcast(), NutEventPost(), NutEventWait(), NutIdle(), NutMsgQSend(), NutSleep(), NutTcpReceive(), NutTcpSend(), NutTcpStateCloseEvent(), ProcessRequests(), Receiver(), and usb2dxm().

uint8_t NutThreadSetPriority ( uint8_t  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.

Changing the priority level to 255 will kill the calling thread.

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.

Parameters:
level New priority level or 255 to kill the thread. Zero specifies the highest priority. The idle thread is running at level 254 (lowest priority). Application threads should use levels from 32 to 253.
Returns:
The old priority of this thread.
Todo:
Using a specific priority level for killing a thread is actually not the best idea. NutThreadKill() can be used instead.

Definition at line 516 of file thread.c.

References NutEnterCritical, NutExitCritical, NutThreadAddPriQueue(), NutThreadKill(), NutThreadRemoveQueue(), NutThreadSwitch(), runningThread, runQueue, TDS_READY, TDS_RUNNING, TRACE_ADD_ITEM, and TRACE_TAG_THREAD_SETPRIO.

Referenced by AhdlcRx(), ALife(), CAN_Tx(), CSNICrx(), Displayer(), dxm2usb(), EmacRxThread(), FeederThread(), High(), Key1Thread(), Key2Thread(), Led(), Low(), main(), NicRx(), NicRxAsix(), NicRxLanc(), NutIdle(), NutTcpSm(), NutThreadExit(), Receiver(), Sc16is752UsartInterruptProcessing(), Sleeper1(), Sleeper2(), Sleeper3(), Sleeper4(), SNTP_resync(), sys_key(), sys_led(), Thread1(), Thread2(), TimerEvent1(), TimerEvent2(), TimerEvent3(), TimerEvent4(), and usb2dxm().

void NutThreadExit ( void   ) 

End the current thread.

Terminates the current thread, in due course the memory associated with the thread will be released back to the OS this is done by the idle thread.

Todo:
NutThreadKill() can be used instead of setting the priority level to 255.

Definition at line 563 of file thread.c.

References NutThreadSetPriority().

void NutThreadDestroy ( void   ) 

Free a thread that was previously killed and release memory back to the OS.

Called when another thread is killed and by the idle thread.

Applications generally do not call this function, however you could call it to try to reclaim memory.

Definition at line 577 of file thread.c.

References killedThread, and NutStackFree.

Referenced by NutIdle(), and NutThreadKill().

void NutThreadKill ( void   ) 

Kill the running thread.

The thread is moved from the schedule que and

Applications generally do not call this function.

Definition at line 592 of file thread.c.

References killedThread, NutThreadDestroy(), nutThreadList, and runningThread.

Referenced by NutThreadSetPriority().

HANDLE GetThreadByName ( char *  name  ) 

Query handle of a thread with a specific name.

Parameters:
name Case sensitive symbolic name of the thread.
Returns:
Handle of the thread, if it exists. Otherwise NULL is returned.
Todo:
Rarely used helper function. Should be placed in a seperate module.

Definition at line 625 of file thread.c.

References nutThreadList, runningThread, and strcmp().


Variable Documentation

NUTTHREADINFO* runningThread

Currently running thread.

Pointer to the NUTTHREADINFO structure of the currently running thread.

Definition at line 246 of file thread.c.

Referenced by GetThreadByName(), NutEventWait(), NutMutexDestroy(), NutMutexLock(), NutMutexTrylock(), NutMutexUnlock(), NutSleep(), NutThreadCreate(), NutThreadKill(), NutThreadResume(), NutThreadSetPriority(), NutThreadSwitch(), and NutThreadYield().

NUTTHREADINFO* killedThread

Thread to be killed.

Pointer to the NUTTHREADINFO structure of the latest killed thread.

Definition at line 254 of file thread.c.

Referenced by NutThreadDestroy(), and NutThreadKill().

NUTTHREADINFO* nutThreadList

List of all created threads.

Linked list of NUTTHREADINFO structures of all threads. New threads are put in front. This list contains at least two threads, the main application thread followed by the idle thread.

Definition at line 264 of file thread.c.

Referenced by GetThreadByName(), NutDumpThreadList(), NutThreadCreate(), NutThreadKill(), NutThreadResume(), and ProcessRequests().

NUTTHREADINFO* runQueue

List of ready-to-run threads.

Priority ordered linked list of NUTTHREADINFO structures of all threads which are ready to run. The idle thread will always remain at the end of this list.

Definition at line 273 of file thread.c.

Referenced by NutEventPostAsync(), NutEventTimeout(), NutEventWait(), NutSleep(), NutThreadCreate(), NutThreadResume(), NutThreadSetPriority(), NutThreadSwitch(), NutThreadWake(), and NutThreadYield().


© 2000-2010 by contributors - visit http://www.ethernut.de/