Mthreads

NAME

mthr_create - create a new mthread

SYNOPSIS

#include <mthread.h>

mthread_p mthr_create(unsigned stacksize, unsigned mode, start_func ufct, void *arg);

DESCRIPTION

mthr_create() creates a new userlevel thread and returns a thread handle that can be used in further calls.

For the new thread a stack of size stacksize will be allocated. If stacksize is zero a default size will be chosen which can be adjusted by mthr_config(3). If stacksize is less than the minimum size configured for the system, the minimum stack size will be used. Be aware that there are no mechanisms to enlarge the stack once a thread has started. Moreover there is no hardware protection that ensures that no stack overflow occures. A stack overflow may crash the whole application.

The option mode controls which type of thread will be created and where the new thread will be enqueued:

DETACHED: A detached thread will be created, i.e. when the thread terminates, all its information will be destroyed and all its memory be freed automatically. There is no possibility to do a mthr_join(3) to retrieve the thread's exitvalue. Without DETACHED a thread is nondetached on default. A nondetached thread will become a zombie after its mthr_exit(3) call. Its stack will be freed, but its thread structure will remain until you free the thread by calling mthr_join(3). If you don't intend to use the thread's exitvalue, use detached threads as they don't consume memory as zombies.
CPU_LOCAL: The new thread will be enqueued on the local CPU's startqueue. This option is useful if you know that the new thread will use the same data that another local thread has used and therefore can use the other thread's cache state.
NODE_LOCAL: The new thread will be enqueued on the local node's startqueue. This option is useful if you know that the new thread will work with node local memory and should therefore be scheduled on the local node.
SC_GLOBAL The new thread will be enqueued on the subcomplexe's startqueue.

Independent of what you specified for mode, a thread can migrate to another CPU and/or another node due to load balancing, but it will be scheduled as near as possible.

start_func is the function that will be executed by the new thread. This function must be of the following type:

void *(*start_func)(void *arg)

Usually this function shouldn't return, but should be terminated by a call to mthr_exit(3). If it returns mthr_exit will be called implicitly, terminating the userlevel thread with exitvalue 0. The start function will be called with arg as the only argument.

RETURN VALUE

mthr_create() returns a handle to the new thread.

EXAMPLE

The following example creates a detached thread with default stacksize that will be enqueued onto the local node's startqueue and which will execute the function hello when it is started:

#include <mthread.h>

void *hello(void *arg)
{
   printf("Hello! %s\n",(char *)arg);
   mthr_exit(0);
}

void main()
{
   mthr_startup();

   mthr_create(0,DETACHED | NODE_LOCAL, hello, "That's a userlevel thread.");

   mthr_exit(0);
}