To use the Solaris threads functions described in this chapter, you must link with the Solaris threads library -lthread).

Where functionality is virtually the same for both Solaris threads and for pthreads, (even though the function names or arguments might differ), only a brief example consisting of the correct include file and the function prototype is presented. Where return values are not given for the Solaris threads functions, see the appropriate pages in man(3): Library Routines for the function return values.

For more information on Solaris related functions, see the related pthreads documentation for the similarly named function.

Where Solaris threads functions offer capabilities that are not available in pthreads, a full description of the functions is provided.

Unique Solaris Threads Functions

• "Suspend Thread Execution"

• "Continue a Suspended Thread"

Suspend Thread Execution

thr_suspend(3THR)

thr_suspend(3THR) 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 return 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(3THR)

thr_continue(3THR) 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 return 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.

Similar Synchronization Functions--Read-Write Locks

Read-write locks allow simultaneous read access by many threads while restricting write access to only one thread at a time.

• "Initialize a Read-Write Lock"

• "Acquire a Read Lock"

• "Try to Acquire a Read Lock"

• "Acquire a Write Lock"

• "Try to Acquire a Write Lock"

• "Unlock a Read-Write Lock"

• "Destroy Read-Write Lock State"

When any thread holds the lock for reading, other threads can also acquire the lock for reading but must wait to acquire the lock for writing. If one thread holds the lock for writing, or is waiting to acquire the lock for writing, other threads must wait to acquire the lock for either reading or writing.

Read-write locks are slower than mutexes, but can improve performance when they protect data that are not frequently written but that are read by many concurrent threads.

Use read-write locks to synchronize threads in this process and other processes by allocating them in memory that is writable and shared among the cooperating processes (see mmap(2)) and by initializing them for this behavior.

By default, the acquisition order is not defined when multiple threads are waiting for a read-write lock. However, to avoid writer starvation, the Solaris threads package tends to favor writers over readers.

Read-write locks must be initialized before use.

Initialize a Read-Write Lock

rwlock_init(3THR)

#include <synch.h>  (or #include <thread.h>)

int rwlock_init(rwlock_t *rwlp, int type, void * arg);

Use rwlock_init(3THR) to initialize the read-write lock pointed to by rwlp and to set the lock state to unlocked. type can be one of the following (note that arg is currently ignored). (For POSIX threads, see "pthread_rwlock_init(3THR)".)

• USYNC_PROCESS The read-write lock can be used to synchronize threads in this process and other processes. arg is ignored.

• USYNC_THREAD The read-write lock can be used to synchronize threads in this process, only. arg is ignored.

Multiple threads must not initialize the same read-write lock simultaneously. Read-write locks can also be initialized by allocation in zeroed memory, in which case a type of USYNC_THREAD is assumed. A read-write lock must not be reinitialized while other threads might be using it.