#include <thread.h>

stand-alone

This macro gives the smallest acceptable size of a thread’s workspace in bytes. The thread creation functions fail and return NULL if the given workspace size is less than this value. Note that most threads probably need considerably more space that this.

stand-alone

A macro giving the priority of normal (not urgent) threads. It has the value 1.

#include <thread.h>

stand-alone

A macro giving the priority of urgent threads. It has the value 0.

#include <thread.h>

void thread_deschedule(void);

stand-alone

stack: 0 bytes

This function causes a thread to become momentarily unable to execute, causing it to be descheduled and allowing some other thread of the same priority to resume execution in its place. Eventually, the thread that called thread_deschedule will resume.

Most applications should never need to use thread_deschedule. If you find yourself wanting to use it, first ask yourself:

The function can be used by a thread to ensure that it does not 'hog' the processor to the detriment of other threads at the same priority. This is particularly important for a thread whose priority is URGENT, as it cannot be pre-empted by a thread of a higher priority nor stopped because it uses up its time-slice.

#include <thread.h>

stand-alone

The type of value returned by a call to thread_new or thread_launch.

#include <thread.h>

THREAD_HANDLE thread_launch (

   void  (*fn)(void *),

   void   *ws,

   size_t  wssize,

   int     priority,

   void   *arg

);

stand-alone

stack: 72 bytes

This function starts a new thread based on the function fn. The new thread stops either when it executes the function thread_stop, or when fn returns.

The new thread uses the 8-byte-aligned area ws as its workspace (stack), which should be wssize octets (eight-bit bytes) long. It may be allocated from the heap using malloc, or it could be a static or auto array variable.

The function returns a (non-zero) handle to the created thread on success. If wssize is less than THREAD_MIN_STACK the function fails and returns 0.

The priority argument defines the priority at which the new thread should run. It is an integer in the range 0–7, where 0 represents the highest priority and 7 the lowest. The header defines the literals THREAD_URGENT and THREAD_NOTURG, corresponding to priority levels 0 and 1 respectively. New threads are often started at the same priority as the thread creating them. You can do this by using the function thread_priority (see below) to provide a value for this argument.

The argument arg is passed to the new thread's function, fn. It could be, for example, a pointer to a simple variable, or to a struct variable containing a number of parameter values. When you pass a pointer to a variable into a thread in this way, you must make sure that the variable does not change before the thread reads it.

By using a cast, it is also possible to pass a value argument to the thread function:

thread_launch(func, ws, 1000, 1, (void *)150);

The func function could take up its argument like this:

void func(void *value) {

   int param = (int)value;

}

In this example, param would take the value 150. Note that this technique does not work with float or double value parameters; they must be passed by reference.

The value returned by the function may be used to refer to the thread (see thread_wait).

See also the description of thread_new, which simplifies thread creation by starting a thread at the current priority and allocating the thread's workspace from the heap.

#include <thread.h>

THREAD_HANDLE thread_new(

   void   (*fn)(void *),

   size_t   wssize,

   void    *arg

);

stand-alone

stack: 96 bytes

The function fn is started as a new thread, running at the same priority as the current thread, with a workspace of wssize octets (eight-bit bytes). This workspace is taken from the heap (using par_malloc); you can return it to the heap by passing the returned THREAD_HANDLE to par_free or free once you know that the thread has stopped.

If there is not enough free heap space to create the workspace or if the size of the workspace is less than THREAD_MIN_STACK, thread_new does not start the thread but returns NULL.

The return value may also be used to wait for the termination of the thread (see thread_wait).

The argument arg is the argument that is passed to the new thread's function, fn. This mechanism is the same as the one used by thread_launch.

thread_new is a shorthand way of calling the more general thread creation function thread_launch in the most common circumstances.

A thread that calls thread_new must not have claimed the par_sema semaphore. This is because par_malloc is used to get the workspace from the heap, and par_malloc itself waits for par_sema. So if par_sema has already been claimed, par_malloc will wait for ever and the call to thread_new will never return.

#include <thread.h>

int thread_priority(void);

stand-alone

stack: 0 bytes

This function returns the priority level of the current thread, which is an integer in the range 0–7. The literals THREAD_URGENT and THREAD_NOTURG are defined in the header to correspond to levels 0 and 1 respectively.

#include <thread.h>

void thread_set_priority (

   int newpri

);

stand-alone

stack: 20 bytes

This function changes the priority of the current thread to newpri, which must be in the range 0–7.

#include <thread.h>

int thread_set_urgent(void);

stand-alone

stack: 20 bytes

This function makes the current thread urgent (priority 0). It returns the priority the thread had previously, allowing the old priority to be restored later by a call to thread_set_priority, if required.

#include <thread.h>

void thread_stop(void);

stand-alone

stack: 72 bytes

This function stops the current thread. The current thread is also stopped if the function in which it started returns. Note that returning from the main function of a task linked against the full run-time library results in the connection with the host being closed. Another thread may wait for the thread to stop by calling the function thread_wait with the thread's handle as argument.

#include <thread.h>

void thread_wait (

   THREAD_HANDLE handle

);

stand-alone

stack: 72 bytes

This function waits for another thread to stop. handle must be the value returned when the thread was created (see thread_launch and thread_new).

For example,

THREAD_HANDLE h = thread_new(my_thread, 4000, 0); // start a thread

do_something();

thread_wait(h);                                   // wait for it to finish