Unique Solaris Threads Functions

• "Suspend Thread Execution"

• "Continue a Suspended Thread"

• "Set Thread Concurrency Level"

• "Get Thread Concurrency"

Suspend Thread Execution

thr_suspend(3T)

thr_suspend() immediately suspends the execution of the thread specified by target_thread. On successful return from thr_suspend(), the suspended thread is no longer executing.

Once a thread is suspended, subsequent calls to thr_suspend() have no effect. Signals cannot awaken the suspended thread; they remain pending until the thread resumes execution.

#include <thread.h>

int thr_suspend(thread_t tid);

In the following synopsis, pthread_t tid as defined in pthreads is the same as thread_t tid in Solaris threads. tid values can be used interchangeably either by assignment or through the use of casts.

thread_t tid; /* tid from thr_create() */

/* pthreads equivalent of Solaris tid from thread created */
/* with pthread_create() */
pthread_t ptid;	

int ret;

ret = thr_suspend(tid);

/* using pthreads ID variable with a cast */
ret = thr_suspend((thread_t) ptid);	

Return Values

thr_suspend() returns zero after completing successfully. Any other returned value indicates that an error occurred. When the following condition occurs, thr_suspend() fails and returns the corresponding value.

ESRCH

tid cannot be found in the current process.

Continue a Suspended Thread

thr_continue(3T)

thr_continue() resumes the execution of a suspended thread. Once a suspended thread is continued, subsequent calls to thr_continue() have no effect.

#include <thread.h>

int thr_continue(thread_t tid);

A suspended thread will not be awakened by a signal. The signal stays pending until the execution of the thread is resumed by thr_continue().

pthread_t tid as defined in pthreads is the same as thread_t tid in Solaris threads. tid values can be used interchangeably either by assignment or through the use of casts.

thread_t tid; /* tid from thr_create()*/

/* pthreads equivalent of Solaris tid from thread created */
/* with pthread_create()*/
pthread_t ptid;	

int ret;

ret = thr_continue(tid);

/* using pthreads ID variable with a cast */
ret = thr_continue((thread_t) ptid)	

Return Values

thr_continue() returns zero after completing successfully. Any other returned value indicates that an error occurred. When the following condition occurs, thr_continue() fails and returns the corresponding value.

ESRCH

tid cannot be found in the current process.

Set Thread Concurrency Level

By default, Solaris threads attempt to adjust the system execution resources (LWPs) used to run unbound threads to match the real number of active threads. While the Solaris threads package cannot make perfect decisions, it at least ensures that the process continues to make progress.

When you have some idea of the number of unbound threads that should be simultaneously active (executing code or system calls), tell the library through thr_setconcurrency(). To get the number of threads being used, use thr_getconcurrency().

thr_setconcurrency(3T)

thr_setconcurrency() provides a hint to the system about the required level of concurrency in the application. The system ensures that a sufficient number of threads are active so that the process continues to make progress.

#include <thread.h>

int new_level;
int ret;

ret = thr_setconcurrency(new_level);

Unbound threads in a process might or might not be required to be simultaneously active. To conserve system resources, the threads system ensures by default that enough threads are active for the process to make progress, and that the process will not deadlock through a lack of concurrency.

Because this might not produce the most effective level of concurrency, thr_setconcurrency() permits the application to give the threads system a hint, specified by new_level, for the desired level of concurrency.

The actual number of simultaneously active threads can be larger or smaller than new_level.

Note that an application with multiple compute-bound threads can fail to schedule all the runnable threads if thr_setconcurrency() has not been called to adjust the level of execution resources.

You can also affect the value for the desired concurrency level by setting the THR_NEW_LWP flag in thr_create(). This effectively increments the current level by one.

Return Values

Returns a zero when it completes successfully. Any other returned value indicates that an error occurred. When any of the following conditions are detected, thr_setconcurrency() fails and returns the corresponding value.

EAGAIN

The specified concurrency level would cause a system resource to be exceeded.

EINVAL

The value for new_level is negative.

Get Thread Concurrency

thr_getconcurrency(3T)

Use thr_getconcurrency() to get the current value of the concurrency level previously set by thr_setconcurrency(). Note that the actual number of simultaneously active threads can be larger or smaller than this number.

#include <thread.h>

int thr_getconcurrency(void)

Return Value

thr_getconcurrency() always returns the current value for the desired concurrency level.