Multithreaded Programming Guide

Create a Thread

The thr_create(3THR) routine is one of the most elaborate of all the Solaris threads library routines.

thr_create(3THR)

Usethr_create(3THR) to add a new thread of control to the current process. (For POSIX threads, see pthread_create(3THR).)

Note that the new thread does not inherit pending signals, but it does inherit priority and signal masks.

#include <thread.h>

int thr_create(void *stack_base, size_t stack_size,
    void *(*start_routine) (void *), void *arg, long flags,
    thread_t *new_thread);

size_t thr_min_stack(void);

stack_baseContains the address for the stack that the new thread uses. If stack_base is NULL then thr_create() allocates a stack for the new thread with at least stack_size bytes.

stack_sizeContains the size, in number of bytes, for the stack that the new thread uses. If stack_size is zero, a default size is used. In most cases, a zero value works best. If stack_size is not zero, it must be greater than the value returned by thr_min_stack().

There is no general need to allocate stack space for threads. The threads library allocates 1 megabyte of virtual memory for each thread's stack with no swap space reserved. (The library uses the -MAP_NORESERVE option of mmap(2) to make the allocations.)

start_routineContains the function with which the new thread begins execution. When start_routine() returns, the thread exits with the exit status set to the value returned by start_routine (see thr_exit(3THR)).

arg—Can be anything that is described by void, which is typically any 4-byte value. Anything larger must be passed indirectly by having the argument point to it.

Note that you can supply only one argument. To get your procedure to take multiple arguments, encode them as one (such as by putting them in a structure).

flags—Specifies attributes for the created thread. In most cases a zero value works best.

The value in flags is constructed from the bitwise inclusive OR of the following:


Note –

When there is no explicit synchronization to prevent it, an unsuspended, detached thread can die and have its thread ID reassigned to another new thread before its creator returns from thr_create().


new_thread—Points to a location (when new_thread is not NULL) where the ID of the new thread is stored when thr_create() is successful. The caller is responsible for supplying the storage this argument points to. The ID is valid only within the calling process.

If you are not interested in this identifier, supply a NULL value to new_thread.

Return Values

thr_create() returns zero when it completes successfully. Any other return value indicates that an error occurred. When any of the following conditions is detected, thr_create() fails and returns the corresponding value.


EAGAIN

A system limit is exceeded, such as when too many LWPs have been created.


ENOMEM

Not enough memory was available to create the new thread.


EINVAL

stack_base is not NULL and stack_size is less than the value returned by thr_min_stack.()

Stack Behavior

Stack behavior in Solaris threads is generally the same as that in pthreads. For more information about stack setup and operation, see About Stacks.

You can get the absolute minimum on stack size by calling thr_min_stack(), which returns the amount of stack space required for a thread that executes a null procedure. Useful threads need more than this, so be very careful when reducing the stack size.

You can specify a custom stack in two ways. The first is to supply a NULL for the stack location, thereby asking the runtime library to allocate the space for the stack, but to supply the desired size in the stacksize parameter to thr_create().

The other approach is to take overall aspects of stack management and supply a pointer to the stack to thr_create(). This means that you are responsible not only for stack allocation but also for stack deallocation—when the thread terminates, you must arrange for the disposal of its stack.

When you allocate your own stack, be sure to append a red zone to its end by calling mprotect(2).