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

Get the Minimal Stack Size

thr_min_stack(3THR)

Use thr_min_stack(3THR) to get the minimum stack size for a thread.

#include <thread.h>

size_t thr_min_stack(void);

thr_min_stack() returns the amount of space needed to execute a null thread (a null thread is a thread that is created to execute a null procedure).

A thread that does more than execute a null procedure should allocate a stack size greater than the size of thr_min_stack().

When a thread is created with a user-supplied stack, the user must reserve enough space to run the thread. In a dynamically linked execution environment, it is difficult to know what the thread minimal stack requirements are.

Most users should not create threads with user-supplied stacks. User-supplied stacks exist only to support applications that require complete control over their execution environments.

Instead, users should let the threads library manage stack allocation. The threads library provides default stacks that should meet the requirements of any created thread.

Get the Thread Identifier

thr_self(3THR)

Use thr_self(3THR) to get the ID of the calling thread. (For POSIX threads, see pthread_self(3THR).)

#include <thread.h>

thread_t thr_self(void);

Yield Thread Execution

thr_yield(3THR)

thr_yield(3THR) causes the current thread to yield its execution in favor of another thread with the same or greater priority; otherwise it has no effect. There is no guarantee that a thread calling thr_yield() will do so.

#include <thread.h>

void thr_yield(void);

Send a Signal to a Thread

thr_kill(3THR)

thr_kill(3THR) sends a signal to a thread. (For POSIX threads, see pthread_kill(3THR).)

#include <thread.h>
#include <signal.h>
int thr_kill(thread_t target_thread, int sig);

Access the Signal Mask of the Calling Thread

thr_sigsetmask(3THR)

Use thr_sigsetmask(3THR) to change or examine the signal mask of the calling thread.

#include <thread.h>
#include <signal.h>
int thr_sigsetmask(int how, const sigset_t *set, sigset_t *oset);

Terminate a Thread

thr_exit(3THR)

Use thr_exit(3THR) to terminate a thread. (For POSIX threads, see pthread_exit(3THR).)

#include <thread.h>

void thr_exit(void *status);

Wait for Thread Termination

thr_join(3THR)

Use thr_join(3THR) to wait for a thread to terminate. (For POSIX threads, see pthread_join(3THR).)

#include <thread.h>

int thr_join(thread_t tid, thread_t *departedid, void **status);

Join specific

#include <thread.h>

thread_t tid;
thread_t departedid;
int ret;
void *status;

/* waiting to join thread "tid" with status */
ret = thr_join(tid, &departedid, &status);

/* waiting to join thread "tid" without status */
ret = thr_join(tid, &departedid, NULL);

/* waiting to join thread "tid" without return id and status */
ret = thr_join(tid, NULL, NULL); 

When the tid is (thread_t)0, then thread_join() waits for any undetached thread in the process to terminate. In other words, when no thread identifier is specified, any undetached thread that exits causes thread_join() to return.

Join any

#include <thread.h>

thread_t tid;
thread_t departedid;
int ret;
void *status;

/* waiting to join any non-detached thread with status */
ret = thr_join(0, &departedid, &status); 

By indicating 0 as the thread id in the Solaris thr_join(), a join will take place when any non detached thread in the process exits. The departedid will indicate the thread ID of the exiting thread.