Creating a Thread

The thr_create(3C) routine is one of the most elaborate of all routines in the Oracle Solaris threads interface.

Use thr_create(3C) to add a new thread of control to the current process. For POSIX threads, see pthread_create Syntax.

thr_create Syntax

#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);

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

stack_base. Contains 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_size. Contains 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, stack_size must be greater than the value returned by thr_min_stack().

In general, you do not need to allocate stack space for threads. The system allocates 1 megabyte of virtual memory for each thread's stack with no reserved swap space. The system uses the –MAP_NORESERVE option of mmap(2) to make the allocations.

start_routine. Contains 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 Syntax.

arg. Can be any variable described by void , which is typically any 4-byte value. Any larger value must be passed indirectly by having the argument point to the variable.

Note that you can supply only one argument. To get your procedure to take multiple arguments, encode the multiple arguments as a single argument, such as by putting the arguments 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 arguments:

• THR_SUSPENDED. Suspends the new thread, and does not execute start_routine until the thread is started by thr_continue(). Use THR_SUSPENDED to operate on the thread, such as changing its priority, before you run the thread.

• THR_DETACHED. Detaches the new thread so that its thread ID and other resources can be reused as soon as the thread terminates. Set THR_DETACHED when you do not want to wait for the thread to terminate.

• THR_BOUND. Permanently binds the new thread to an LWP. The new thread is a bound thread. Starting with the Solaris 9 release, no distinction is made by the system between bound and unbound threads. All threads are treated as bound threads.

• THR_DAEMON. Marks the new thread as a daemon. A daemon thread is always detached. THR_DAEMON implies THR_DETACHED. The process exits when all nondaemon threads exit. Daemon threads do not affect the process exit status and are ignored when counting the number of thread exits.

  A process can exit either by calling exit() or by having every thread in the process that was not created with the THR_DAEMON flag call thr_exit(3C). An application or a library that the process calls can create one or more threads that should be ignored (not counted) in the decision of whether to exit. The THR_DAEMON flag identifies threads that are not counted in the process exit criterion.

new_thread. When new_thread is not NULL, it points to where the ID of the new thread is stored when thr_create() is successful. The caller is responsible for supplying the storage pointed to by this argument. The ID is valid only within the calling process.

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

thr_create Return Values

thr_create() returns zero when the function 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.

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

Description: Insufficient memory was available to create the new thread.

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