This chapter compares the application programming interface (API) for Solaris and POSIX threads, and explains the Solaris features that are not found in POSIX threads. The chapter discusses the following topics:
The Solaris threads API and the pthreads API are two solutions to the same problem: build parallelism into application software. Although each API is complete, you can safely mix Solaris threads functions and pthread functions in the same program.
The two APIs do not match exactly, however. Solaris threads support functions that are not found in pthreads, and pthreads include functions that are not supported in the Solaris interface. For those functions that do match, the associated arguments might not, although the information content is effectively the same.
By combining the two APIs, you can use features not found in one API to enhance the other API. Similarly, you can run applications that use Solaris threads exclusively with applications that use pthreads exclusively on the same system.
Solaris threads and pthreads are very similar in both API action and syntax. The major differences are listed in Table 6–1 .
Table 6–1 Unique Solaris Threads and pthreads Features
Solaris Threads |
POSIX Threads |
---|---|
thr_ prefix for threads function names, sema_ prefix for semaphore function names |
pthread_ prefix for pthreads function names, sem_ prefix for semaphore function names |
Ability to create “daemon” threads |
Cancellation semantics |
Suspending and continuing a thread |
Scheduling policies |
The following table compares Solaris threads functions with pthreads functions. Note that even when Solaris threads and pthreads functions appear to be essentially the same, the arguments to the functions can differ.
When a comparable interface is not available either in pthreads or Solaris threads, a hyphen `-' appears in the column. Entries in the pthreads column that are followed by (3RT) are functions in librt, the POSIX.1b Realtime Extensions library, which is not part of pthreads. Functions in this library provide most of the interfaces specified by the POSIX.1b Realtime Extension.
Table 6–2 Solaris Threads and POSIX pthreads Comparison
Solaris Threads |
pthreads |
---|---|
thr_create() |
pthread_create() |
thr_exit() |
pthread_exit() |
thr_join() |
pthread_join() |
thr_yield() |
sched_yield()(3RT) |
thr_self() |
pthread_self() |
thr_kill() |
pthread_kill() |
thr_sigsetmask() |
pthread_sigmask() |
thr_setprio() |
pthread_setschedparam() |
thr_getprio() |
pthread_getschedparam() |
thr_setconcurrency() |
pthread_setconcurrency() |
thr_getconcurrency() |
pthread_getconcurrency() |
thr_suspend() |
- |
thr_continue() |
- |
thr_keycreate() |
pthread_key_create() |
- |
pthread_key_delete() |
thr_setspecific() |
pthread_setspecific() |
thr_getspecific() |
pthread_getspecific() |
- |
pthread_once() |
- |
pthread_equal() |
- |
pthread_cancel() |
- |
pthread_testcancel() |
- |
pthread_cleanup_push() |
- |
pthread_cleanup_pop() |
- |
pthread_setcanceltype() |
- |
pthread_setcancelstate() |
mutex_lock() |
pthread_mutex_lock() |
mutex_unlock() |
pthread_mutex_unlock() |
mutex_trylock() |
pthread_mutex_trylock() |
mutex_init() |
pthread_mutex_init() |
mutex_destroy() |
pthread_mutex_destroy() |
cond_wait() |
pthread_cond_wait() |
cond_timedwait() |
pthread_cond_timedwait() |
cond_reltimedwait() |
pthread_cond_reltimedwait_np() |
cond_signal() |
pthread_cond_signal() |
cond_broadcast() |
pthread_cond_broadcast() |
cond_init() |
pthread_cond_init() |
cond_destroy() |
pthread_cond_destroy() |
rwlock_init() |
pthread_rwlock_init() |
rwlock_destroy() |
pthread_rwlock_destroy() |
rw_rdlock() |
pthread_rwlock_rdlock() |
rw_wrlock() |
pthread_rwlock_wrlock() |
rw_unlock() |
pthread_rwlock_unlock() |
rw_tryrdlock() |
pthread_rwlock_tryrdlock() |
rw_trywrlock() |
pthread_rwlock_trywrlock() |
- |
pthread_rwlockattr_init() |
- |
pthread_rwlockattr_destroy() |
- |
pthread_rwlockattr_getpshared() |
- |
pthread_rwlockattr_setpshared() |
sema_init() |
sem_init()(3RT) |
sema_destroy() |
sem_destroy()(3RT) |
sema_wait() |
sem_wait()(3RT) |
sema_post() |
sem_post()(3RT) |
sema_trywait() |
sem_trywait()(3RT) |
fork1() |
fork() |
- |
pthread_atfork() |
forkall(), multiple thread copy |
- |
- |
pthread_mutexattr_init() |
- |
pthread_mutexattr_destroy() |
type argument in mutex_init() |
pthread_mutexattr_setpshared() |
- |
pthread_mutexattr_getpshared() |
- |
pthread_mutex_attr_settype() |
- |
pthread_mutex_attr_gettype() |
- |
pthread_condattr_init() |
- |
pthread_condattr_destroy() |
type argument in cond_init() |
pthread_condattr_setpshared() |
- |
pthread_condattr_getpshared() |
- |
pthread_attr_init() |
- |
pthread_attr_destroy() |
THR_BOUND flag in thr_create() |
pthread_attr_setscope() |
- |
pthread_attr_getscope() |
- |
pthread_attr_setguardsize() |
- |
pthread_attr_getguardsize() |
stack_size argument in thr_create() |
pthread_attr_setstacksize() |
- |
pthread_attr_getstacksize() |
stack_addr argument in thr_create() |
pthread_attr_setstack() |
- |
pthread_attr_getstack() |
THR_DETACH flag in thr_create() |
pthread_attr_setdetachstate() |
- |
pthread_attr_getdetachstate() |
- |
pthread_attr_setschedparam() |
- |
pthread_attr_getschedparam() |
- |
pthread_attr_setinheritsched() |
- |
pthread_attr_getinheritsched() |
- |
pthread_attr_setsschedpolicy() |
- |
pthread_attr_getschedpolicy() |
To use the Solaris threads functions described in this chapter for Solaris 9 and previous releases, you must link with the Solaris threads library -lthread .
Operation 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 pages section 3: Basic Library Functions 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.
This section describes unique Solaris threads functions: suspending thread execution and continuing a suspended thread.
thr_suspend(3C) immediately suspends the execution of the thread specified by target_thread. On successful return from thr_suspend(), the suspended thread is no longer executing.
Because thr_suspend()suspends the target thread with no regard to the locks that the thread might be holding, you must use thr_suspend() with extreme care. If the suspending thread calls a function that requires a lock held by the suspended target thread, deadlock will result.
#include <thread.h> int thr_suspend(thread_t tid);
After a thread is suspended, subsequent calls to thr_suspend() have no effect. Signals cannot awaken the suspended thread. The signals remain pending until the thread resumes execution.
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);
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
Description:tid cannot be found in the current process.
thr_continue(3C) 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 is not awakened by a signal. The signal remains 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)
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
Description:tid cannot be found in the current process.
Read-write locks allow simultaneous read access by many threads while restricting write access to only one thread at a time. This section discusses the following topics:
Initializing a readers/writer lock
Acquiring a read lock
Trying to acquire a read lock
Acquiring a write lock
Trying to acquire a write
Unlocking a readers/writer lock
Destroying readers/writer 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 read-write locks can improve performance when the locks protect data not frequently written but are read by many concurrent threads.
Use read-write locks to synchronize threads in this process and other processes. Allocate read-write locks in memory that is writable and shared among the cooperating processes. See themmap(2) man page for information about mapping read-write locks 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 of equal priority.
Read-write locks must be initialized before use.
Use rwlock_init(3C) to initialize the read-write lock pointed to by rwlp and to set the lock state to unlocked.
#include <synch.h> (or #include <thread.h>) int rwlock_init(rwlock_t *rwlp, int type, void * arg);
type can be one of the following values:
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 the lock.
For POSIX threads, see pthread_rwlock_init Syntax .
#include <thread.h> rwlock_t rwlp; int ret; /* to be used within this process only */ ret = rwlock_init(&rwlp, USYNC_THREAD, 0);
#include <thread.h> rwlock_t rwlp; int ret; /* to be used among all processes */ ret = rwlock_init(&rwlp, USYNC_PROCESS, 0);
rwlock_init() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EINVAL
Description:Invalid argument.
EFAULT
Description:rwlp or arg points to an illegal address.
Use rw_rdlock(3C) to acquire a read lock on the read-write lock pointed to by rwlp.
#include <synch.h> (or #include <thread.h>) int rw_rdlock(rwlock_t *rwlp);
When the read-write lock is already locked for writing, the calling thread blocks until the write lock is released. Otherwise, the read lock is acquired. For POSIX threads, see pthread_rwlock_rdlock Syntax.
rw_rdlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EINVAL
Description:Invalid argument.
EFAULT
Description:rwlp points to an illegal address.
Use rw_tryrdlock(3C) to attempt to acquire a read lock on the read-write lock pointed to by rwlp.
#include <synch.h> (or #include <thread.h>) int rw_tryrdlock(rwlock_t *rwlp);
When the read-write lock is already locked for writing, rw_tryrdlock() returns an error. Otherwise, the read lock is acquired. For POSIX threads, see pthread_rwlock_tryrdlock Syntax.
rw_tryrdlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EINVAL
Description:Invalid argument.
EFAULT
Description:rwlp points to an illegal address.
EBUSY
Description:The read-write lock pointed to by rwlp was already locked.
Use rw_wrlock(3C) to acquire a write lock on the read-write lock pointed to by rwlp.
#include <synch.h> (or #include <thread.h>) int rw_wrlock(rwlock_t *rwlp);
When the read-write lock is already locked for reading or writing, the calling thread blocks until all read locks and write locks are released. Only one thread at a time can hold a write lock on a read-write lock. For POSIX threads, see pthread_rwlock_wrlock Syntax.
rw_wrlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EINVAL
Description:Invalid argument.
EFAULT
Description:rwlp points to an illegal address.
Use rw_trywrlock(3C) to attempt to acquire a write lock on the read-write lock pointed to by rwlp.
#include <synch.h> (or #include <thread.h>) int rw_trywrlock(rwlock_t *rwlp);
When the read-write lock is already locked for reading or writing, rw_trywrlock() returns an error. For POSIX threads, see pthread_rwlock_trywrlock Syntax.
rw_trywrlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EINVAL
Description:Invalid argument.
EFAULT
Description:rwlp points to an illegal address.
EBUSY
Description:The read-write lock pointed to by rwlp was already locked.
Use rw_unlock(3C) to unlock a read-write lock pointed to by rwlp.
#include <synch.h> (or #include <thread.h>) int rw_unlock(rwlock_t *rwlp);
The read-write lock must be locked, and the calling thread must hold the lock either for reading or writing. When any other threads are waiting for the read-write lock to become available, one of the threads is unblocked. For POSIX threads, see pthread_rwlock_unlock Syntax.
rw_unlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EINVAL
Description:Invalid argument.
EFAULT
Description:rwlp points to an illegal address.
Use rwlock_destroy(3C) to destroy any state that is associated with the read-write lock pointed to by rlwp.
#include <synch.h> (or #include <thread.h>) int rwlock_destroy(rwlock_t *rwlp);
The space for storing the read-write lock is not freed. For POSIX threads, see pthread_rwlock_destroy Syntax.
Example 6–1 uses a bank account to demonstrate read-write locks. While the program could allow multiple threads to have concurrent read-only access to the account balance, only a single writer is allowed. Note that the get_balance() function needs the lock to ensure that the addition of the checking and saving balances occurs atomically.
rwlock_t account_lock; float checking_balance = 100.0; float saving_balance = 100.0; ... rwlock_init(&account_lock, 0, NULL); ... float get_balance() { float bal; rw_rdlock(&account_lock); bal = checking_balance + saving_balance; rw_unlock(&account_lock); return(bal); } void transfer_checking_to_savings(float amount) { rw_wrlock(&account_lock); checking_balance = checking_balance - amount; saving_balance = saving_balance + amount; rw_unlock(&account_lock); }
rwlock_destroy() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.
EINVAL
Description:Invalid argument.
EFAULT
Description:rwlp points to an illegal address.
Operation |
Related Function Description |
---|---|
Create a thread | |
Get the minimal stack size | |
Get the thread identifier | |
Yield thread execution | |
Send a signal to a thread | |
Access the signal mask of the calling thread | |
Terminate a thread | |
Wait for thread termination | |
Create a thread-specific data key | |
Set thread-specific data | |
Get thread-specific data | |
Set the thread priority | |
Get the thread priority |
The thr_create(3C) routine is one of the most elaborate of all routines in the 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.
#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.
When no explicit synchronization is allocated, an unsuspended, detached thread can fail. On failure, the thread ID is reassigned to another new thread before its creator returns from thr_create().
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() 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.
EAGAIN
Description:A system limit is exceeded, such as when too many LWPs have been created.
ENOMEM
Description:Insufficient memory was available to create the new thread.
EINVAL
Description:stack_base is not NULL and stack_size is less than the value returned by thr_min_stack.()
Use thr_min_stack(3C) to get the minimum stack size for a thread.
Stack behavior in Solaris threads is generally the same as stack behavior in pthreads. For more information about stack setup and operation, see About Stacks.
#include <thread.h> size_t thr_min_stack(void);
thr_min_stack() returns the amount of space that is needed to execute a null thread. A null thread is a thread that is created to execute a null procedure. Useful threads need more than the absolute minimum stack size, so be very careful when reducing the stack size.
A thread that executes more than a null procedure should allocate a stack size that is larger 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. A dynamically linked execution environment increases the difficulty of determining the thread minimal stack requirements.
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 the thread's stack.
When you allocate your own stack, be sure to append a red zone to its end by calling mprotect(2).
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 system manage stack allocation. The system provides default stacks that should meet the requirements of any created thread.
No errors are defined.
Use thr_self(3C) to get the ID of the calling thread. For POSIX threads, see pthread_self Syntax.
#include <thread.h> thread_t thr_self(void);
No errors are defined.
thr_yield(3C) causes the current thread to yield its execution in favor of another thread with the same or greater priority. Otherwise, thr_yield() has no effect. However, calling thr_yield() does not guarantee that the thread yields its execution.
#include <thread.h> void thr_yield(void);
thr_yield() returns nothing and does not set errno .
thr_kill(3C) sends a signal to a thread. For POSIX threads, see pthread_kill Syntax.
#include <thread.h> #include <signal.h> int thr_kill(thread_t target_thread, int sig);
Upon successful completion, thr_kill() returns 0. When any of the following conditions is detected, thr_kill() fails and returns the corresponding value. When a failure occurs, no signal is sent.
ESRCH
Description:No thread was found associated with the thread designated by thread ID.
EINVAL
Description:The sig argument value is not zero. sig is an invalid or unsupported signal number.
Use thr_sigsetmask(3C) 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);
thr_sigsetmask() changes or examines a calling thread's signal mask. Each thread has its own signal mask. A new thread inherits the calling thread's signal mask and priority. However, pending signals are not inherited. Pending signals for a new thread will be empty.
If the value of the argument set is not NULL, set points to a set of signals that can modify the currently blocked set. If the value of set is NULL, the value of how is insignificant and the thread's signal mask is unmodified. Use this behavior to inquire about the currently blocked signals.
The value of how specifies the method in which the set is changed. how takes one of the following values.
SIG_BLOCK. set corresponds to a set of signals to block. The signals are added to the current signal mask.
SIG_UNBLOCK. set corresponds to a set of signals to unblock. These signals are deleted from the current signal mask.
SIG_SETMASK. set corresponds to the new signal mask. The current signal mask is replaced by set.
Upon successful completion, thr_sigsetmask() returns 0. When any of the following conditions is detected, thr_sigsetmask() fails and returns the corresponding value.
EINVAL
Description:set is not NULL and the value of how is not defined.
Use thr_exit(3C) to terminate a thread. For POSIX threads, see pthread_exit Syntax.
#include <thread.h> void thr_exit(void *status);
thr_exit() does not return to its caller.
Use thr_join(3C) to wait for a target thread to terminate. For POSIX threads, see pthread_join Syntax.
#include <thread.h> int thr_join(thread_t tid, thread_t *departedid, void **status);
The target thread must be a member of the current process. The target thread cannot be a detached thread or a daemon thread.
Several threads cannot wait for the same thread to complete. One thread will complete successfully. The others will terminate with an ESRCH error.
thr_join() will not block processing of the calling thread if the target thread has already terminated.
#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.
#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 takes place when any non detached thread in the process exits. The departedid indicates the thread ID of the exiting thread.
thr_join() returns 0 if successful. When any of the following conditions is detected, thr_join() fails and returns the corresponding value.
ESRCH
Description:No undetached thread is found which corresponds to the target thread ID.
EDEADLK
Description:A deadlock was detected or the value of the target thread specifies the calling thread.
thr_keycreate(3C) allocates a key that is used to identify thread-specific data in a process. The key is global to all threads in the process. Each thread binds a value to the key when the key gets created.
Except for the function names and arguments, thread-specific data is the same for Solaris threads as thread-specific data is for POSIX threads. The synopses for the Solaris functions are described in this section. For POSIX threads, see pthread_key_create Syntax.
#include <thread.h> int thr_keycreate(thread_key_t *keyp, void (*destructor) (void *value));
keyp independently maintains specific values for each binding thread. Each thread is initially bound to a private element of keyp that allows access to its thread-specific data. Upon key creation, a new key is assigned the value NULL for all active threads. Additionally, upon thread creation, all previously created keys in the new thread are assigned the value NULL.
An optional destructor function can be associated with each keyp. Upon thread exit, if a keyp has a non-NULL destructor and the thread has a non-NULL value associated with keyp , the destructor is called with the currently associated value. If more than one destructor exists for a thread when it exits, the order of destructor calls is unspecified.
thr_keycreate() returns 0 if successful. When any of the following conditions is detected, thr_keycreate() fails and returns the corresponding value.
EAGAIN
Description:The system does not have the resources to create another thread-specific data key, or the number of keys exceeds the per-process limit for PTHREAD_KEYS_MAX.
ENOMEM
Description:Insufficient memory is available to associate value with keyp.
thr_setspecific(3C) binds value to the thread-specific data key, key, for the calling thread. For POSIX threads, see pthread_setspecific Syntax.
#include <thread.h> int thr_setspecific(thread_key_t key, void *value);
thr_setspecific() returns 0 if successful. When any of the following conditions is detected, thr_setspecific() fails and returns the corresponding value.
ENOMEM
Description:Insufficient memory is available to associate value with keyp.
EINVAL
Description:keyp is invalid.
thr_getspecific(3C) stores the current value bound to key for the calling thread into the location pointed to by valuep. For POSIX threads, see pthread_getspecific Syntax.
#include <thread.h> int thr_getspecific(thread_key_t key, void **valuep);
thr_getspecific() returns 0 if successful. When any of the following conditions is detected, thr_getspecific() fails and returns the corresponding value.
ENOMEM
Description:Insufficient memory is available to associate value with keyp.
EINVAL
Description:keyp is invalid.
In Solaris threads, a thread created with a priority other than the priority of its parents is created in SUSPEND mode. While suspended, the thread's priority is modified using the thr_setprio(3C) function call. After thr_setprio() completes, the thread resumes execution.
A higher priority thread receives precedence over lower priority threads with respect to synchronization object contention.
thr_setprio(3C) changes the priority of the thread, specified by tid, within the current process to the priority specified by newprio. For POSIX threads, see pthread_setschedparam Syntax.
#include <thread.h> int thr_setprio(thread_t tid, int newprio)
The range of valid priorities for a thread depends on its scheduling policy.
thread_t tid; int ret; int newprio = 20; /* suspended thread creation */ ret = thr_create(NULL, NULL, func, arg, THR_SUSPENDED, &tid); /* set the new priority of suspended child thread */ ret = thr_setprio(tid, newprio); /* suspended child thread starts executing with new priority */ ret = thr_continue(tid);
thr_setprio() returns 0 if successful. When any of the following conditions is detected, thr_setprio() fails and returns the corresponding value.
ESRCH
Description:The value specified by tid does not refer to an existing thread.
EINVAL
Description:The value of priority is invalid for the scheduling policy of the specified thread.
EPERM
Description:The caller does not have the appropriate permission to set the priority to the value specified.
Use thr_getprio(3C) to get the current priority for the thread. Each thread inherits a priority from its creator. thr_getprio() stores the current priority, tid, in the location pointed to by newprio. For POSIX threads, see pthread_getschedparam Syntax.
#include <thread.h> int thr_getprio(thread_t tid, int *newprio)
thr_getprio() returns 0 if successful. When the following condition is detected, thr_getprio() fails and returns the corresponding value.
ESRCH
Description:The value specified by tid does not refer to an existing thread.
Initializing a mutex
Destroying a mutex
Acquiring a mutex
Releasing a mutex
Trying to acquire a mutex
Use mutex_init(3C) to initialize the mutex pointed to by mp. For POSIX threads, see Initializing a Mutex.
#include <synch.h> #include <thread.h> int mutex_init(mutex_t *mp, int type, void *arg));
The type can be one of the following values.
USYNC_PROCESS. The mutex can be used to synchronize threads in this process and other processes. arg is ignored.
USYNC_PROCESS_ROBUST. The mutex can be used to robustly synchronize threads in this process and other processes. arg is ignored.
USYNC_THREAD. The mutex can be used to synchronize threads in this process only. arg is ignored.
When a process fails while holding a USYNC_PROCESS lock, subsequent requestors of that lock hang. This behavior is a problem for systems that share locks with client processes because the client processes can be abnormally killed. To avoid the problem of hanging on a lock held by a dead process, use USYNC_PROCESS_ROBUST to lock the mutex. USYNC_PROCESS_ROBUST adds two capabilities:
In the case of process death, all owned locks held by that process are unlocked.
The next requestor for any of the locks owned by the failed process receives the lock. But, the lock is held with an error return indicating that the previous owner failed while holding the lock.
Mutexes can also be initialized by allocation in zeroed memory, in which case a type of USYNC_THREAD is assumed.
Multiple threads must not initialize the same mutex simultaneously. A mutex lock must not be reinitialized while other threads might be using the mutex.
#include <thread.h> mutex_t mp; int ret; /* to be used within this process only */ ret = mutex_init(&mp, USYNC_THREAD, 0);
#include <thread.h> mutex_t mp; int ret; /* to be used among all processes */ ret = mutex_init(&mp, USYNC_PROCESS, 0);
#include <thread.h> mutex_t mp; int ret; /* to be used among all processes */ ret = mutex_init(&mp, USYNC_PROCESS_ROBUST, 0);
mutex_init() returns 0 if successful. When any of the following conditions is detected, mutex_init() fails and returns the corresponding value.
EFAULT
Description:mp points to an illegal address.
EINVAL
Description:The value specified by mp is invalid.
ENOMEM
Description:System has insufficient memory to initialize the mutex.
EAGAIN
Description:System has insufficient resources to initialize the mutex.
EBUSY
Description:System detected an attempt to reinitialize an active mutex.
Use mutex_destroy(3C) to destroy any state that is associated with the mutex pointed to by mp . The space for storing the mutex is not freed. For POSIX threads, see pthread_mutex_destroy Syntax.
#include <thread.h> int mutex_destroy (mutex_t *mp);
mutex_destroy() returns 0 if successful. When the following condition is detected, mutex_destroy() fails and returns the corresponding value.
EFAULT
Description:mp points to an illegal address.
Use mutex_lock(3C) to lock the mutex pointed to by mp. When the mutex is already locked, the calling thread blocks until the mutex becomes available. Blocked threads wait on a prioritized queue. For POSIX threads, see pthread_mutex_lock Syntax.
#include <thread.h> int mutex_lock(mutex_t *mp);
mutex_lock() returns 0 if successful. When any of the following conditions is detected, mutex_lock() fails and returns the corresponding value.
EFAULT
Description:mp points to an illegal address.
EDEADLK
Description:The mutex is already locked and is owned by the calling thread.
Use mutex_unlock(3C) to unlock the mutex pointed to by mp. The mutex must be locked. The calling thread must be the thread that last locked the mutex, the owner. For POSIX threads, see pthread_mutex_unlock Syntax.
#include <thread.h> int mutex_unlock(mutex_t *mp);
mutex_unlock() returns 0 if successful. When any of the following conditions is detected, mutex_unlock() fails and returns the corresponding value.
EFAULT
Description:mp points to an illegal address.
EPERM
Description:The calling thread does not own the mutex.
Use mutex_trylock(3C) to attempt to lock the mutex pointed to by mp. This function is a nonblocking version of mutex_lock(). For POSIX threads, see pthread_mutex_trylock Syntax.
#include <thread.h> int mutex_trylock(mutex_t *mp);
mutex_trylock() returns 0 if successful. When any of the following conditions is detected, mutex_trylock() fails and returns the corresponding value.
EFAULT
Description:mp points to an illegal address.
EBUSY
Description:The system detected an attempt to reinitialize an active mutex.
Initializing a condition variable
Destroying a condition variable
Waiting for a condition
Waiting for an absolute time
Waiting for a time interval
Unblocking one thread
Unblocking all threads
Use cond_init(3C) to initialize the condition variable pointed to by cv.
#include <thread.h> int cond_init(cond_t *cv, int type, int arg);
The type can be one of the following values:
USYNC_PROCESS. The condition variable can be used to synchronize threads in this process and other processes. arg is ignored.
USYNC_THREAD The condition variable can be used to synchronize threads in this process only. arg is ignored.
Condition variables can also be initialized by allocation in zeroed memory, in which case a type of USYNC_THREAD is assumed.
Multiple threads must not initialize the same condition variable simultaneously. A condition variable must not be reinitialized while other threads might be using the condition variable.
For POSIX threads, see pthread_condattr_init Syntax .
#include <thread.h> cond_t cv; int ret; /* to be used within this process only */ ret = cond_init(cv, USYNC_THREAD, 0);
#include <thread.h> cond_t cv; int ret; /* to be used among all processes */ ret = cond_init(&cv, USYNC_PROCESS, 0);
cond_init() returns 0 if successful. When any of the following conditions is detected, cond_init() fails and returns the corresponding value.
EFAULT
Description:cv points to an illegal address.
EINVAL
Description:type is not a recognized type.
Use cond_destroy(3C) to destroy state that is associated with the condition variable pointed to by cv . The space for storing the condition variable is not freed. For POSIX threads, see pthread_condattr_destroy Syntax.
#include <thread.h> int cond_destroy(cond_t *cv);
cond_destroy() returns 0 if successful. When any of the following conditions is detected, cond_destroy() fails and returns the corresponding value.
EFAULT
Description:cv points to an illegal address.
EBUSY
Description:The system detected an attempt to destroy an active condition variable.
Use cond_wait(3C) to atomically release the mutex pointed to by mp and cause the calling thread to block on the condition variable pointed to by cv. The blocked thread can be awakened by cond_signal(), cond_broadcast() , or when interrupted by delivery of a signal or a fork().
cond_wait() always returns with the mutex locked and owned by the calling thread, even when returning an error.
#include <thread.h> int cond_wait(cond_t *cv, mutex_t *mp);
cond_wait() returns 0 if successful. When any of the following conditions is detected, cond_wait() fails and returns the corresponding value.
EFAULT
Description:cv points to an illegal address.
EINTR
Description:The wait was interrupted by a signal.
cond_timedwait(3C) is very similar to cond_wait(), except that cond_timedwait() does not block past the time of day specified by abstime . For POSIX threads, see pthread_cond_timedwait Syntax.
#include <thread.h> int cond_timedwait(cond_t *cv, mutex_t *mp, timestruct_t abstime);
cond_timedwait() always returns with the mutex locked and owned by the calling thread, even when returning an error.
The cond_timedwait() function blocks until the condition is signaled or until the time of day specified by the last argument has passed. The timeout is specified as the time of day so the condition can be retested efficiently without recomputing the time-out value.
cond_timedwait() returns 0 if successful. When any of the following conditions is detected, cond_timedwait() fails and returns the corresponding value.
EFAULT
Description:cv points to an illegal address.
ETIME
Description:The time specified by abstime has expired.
EINVAL
Description:abstime is invalid.
cond_reltimedwait(3C) is very similar to cond_timedwait(), except for the value for the third argument. cond_reltimedwait() takes a relative time interval value in its third argument rather than an absolute time of day value. For POSIX threads, see the pthread_cond_reltimedwait_np(3C) man page.
cond_reltimedwait() always returns with the mutex locked and owned by the calling thread even when returning an error. The cond_reltimedwait() function blocks until the condition is signaled or until the time interval specified by the last argument has elapsed.
#include <thread.h> int cond_reltimedwait(cond_t *cv, mutex_t *mp, timestruct_t reltime);
cond_reltimedwait() returns 0 if successful. When any of the following conditions is detected, cond_reltimedwait() fails and returns the corresponding value.
EFAULT
Description:cv points to an illegal address.
ETIME
Description:The time specified by reltime has expired.
Use cond_signal(3C) to unblock one thread that is blocked on the condition variable pointed to by cv . If no threads are blocked on the condition variable, cond_signal() has no effect.
#include <thread.h> int cond_signal(cond_t *cv);
cond_signal() returns 0 if successful. When the following condition is detected, cond_signal() fails and returns the corresponding value.
EFAULT
Description:cv points to an illegal address.
Use cond_broadcast(3C) to unblock all threads that are blocked on the condition variable pointed to by cv. When no threads are blocked on the condition variable, then cond_broadcast() has no effect.
#include <thread.h> int cond_broadcast(cond_t *cv);
cond_broadcast() returns 0 if successful. When the following condition is detected, cond_broadcast() fails and returns the corresponding value.
EFAULT
Description:cv points to an illegal address.
Semaphore operations are the same in both the Solaris Operating Environment and the POSIX environment. The function name changed from sema_ in the Solaris Operating Environment to sem_ in pthreads. This section discusses the following topics:
Initializing a semaphore
Incrementing a semaphore
Blocking on a semaphore count
Decrementing a semaphore count
Destroying the semaphore state
Use sema_init(3C) to initialize the semaphore variable pointed to by sp by count amount.
#include <thread.h> int sema_init(sema_t *sp, unsigned int count, int type, void *arg);
type can be one of the following values:
USYNC_PROCESS. The semaphore can be used to synchronize threads in this process and other processes. Only one process should initialize the semaphore. arg is ignored.
USYNC_THREAD. The semaphore can be used to synchronize threads in this process, only. arg is ignored.
Multiple threads must not initialize the same semaphore simultaneously. A semaphore must not be reinitialized while other threads might be using the semaphore.
#include <thread.h> sema_t sp; int ret; int count; count = 4; /* to be used within this process only */ ret = sema_init(&sp, count, USYNC_THREAD, 0);
#include <thread.h> sema_t sp; int ret; int count; count = 4; /* to be used among all the processes */ ret = sema_init (&sp, count, USYNC_PROCESS, 0);
sema_init() returns 0 if successful. When any of the following conditions is detected, sema_init() fails and returns the corresponding value.
EINVAL
Description:sp refers to an invalid semaphore.
EFAULT
Description:Either sp or arg point to an illegal address.
Use sema_post(3C) to atomically increment the semaphore pointed to by sp. When any threads are blocked on the semaphore, one thread is unblocked.
#include <thread.h> int sema_post(sema_t *sp);
sema_post() returns 0 if successful. When any of the following conditions is detected, sema_post() fails and returns the corresponding value.
EINVAL
Description:sp refers to an invalid semaphore.
EFAULT
Description:sp points to an illegal address.
EOVERFLOW
Description:The semaphore value pointed to by sp exceeds SEM_VALUE_MAX.
Use sema_wait(3C) to block the calling thread until the count in the semaphore pointed to by sp becomes greater than zero. When the count becomes greater than zero, atomically decrement the count.
#include <thread.h> int sema_wait(sema_t *sp);
sema_wait() returns 0 if successful. When any of the following conditions is detected, sema_wait() fails and returns the corresponding value.
EINVAL
Description:sp refers to an invalid semaphore.
EINTR
Description:The wait was interrupted by a signal.
Use sema_trywait(3C) to atomically decrement the count in the semaphore pointed to by sp when the count is greater than zero. This function is a nonblocking version of sema_wait().
#include <thread.h> int sema_trywait(sema_t *sp);
sema_trywait() returns 0 if successful. When any of the following conditions is detected, sema_trywait() fails and returns the corresponding value.
EINVAL
Description:sp refers to an invalid semaphore.
EBUSY
Description:The semaphore pointed to by sp has a zero count.
Use sema_destroy(3C) to destroy any state that is associated with the semaphore pointed to by sp. The space for storing the semaphore is not freed.
#include <thread.h> int sema_destroy(sema_t *sp);
sema_destroy() returns 0 if successful. When the following condition is detected, sema_destroy() fails and returns the corresponding value.
EINVAL
Description:sp refers to an invalid semaphore.
Each of the synchronization primitives can be set up to be used across process boundaries. This cross-boundary setup is done by ensuring that the synchronization variable is located in a shared memory segment and by calling the appropriate init routine with type set to USYNC_PROCESS.
If type is set to USYNC_PROCESS, then the operations on the synchronization variables work just as the variables do when type is USYNC_THREAD.
mutex_init(&m, USYNC_PROCESS, 0); rwlock_init(&rw, USYNC_PROCESS, 0); cond_init(&cv, USYNC_PROCESS, 0); sema_init(&s, count, USYNC_PROCESS, 0);
Example 6–2 shows the producer and consumer problem with the producer and consumer in separate processes. The main routine maps zero-filled memory that main shares with its child process, into its address space. Note that mutex_init() and cond_init() must be called because the type of the synchronization variables is USYNC_PROCESS.
A child process is created to run the consumer. The parent runs the producer.
This example also shows the drivers for the producer and consumer. The producer_driver reads characters from stdin and calls the producer. The consumer_driver gets characters by calling the consumer and writes them to stdout.
The data structure for Example 6–2 is the same as that used for the solution with condition variables. See Examples of Using Nested Locking With a Singly-Linked List .
main() { int zfd; buffer_t *buffer; zfd = open(“/dev/zero”, O_RDWR); buffer = (buffer_t *)mmap(NULL, sizeof(buffer_t), PROT_READ|PROT_WRITE, MAP_SHARED, zfd, 0); buffer->occupied = buffer->nextin = buffer->nextout = 0; mutex_init(&buffer->lock, USYNC_PROCESS, 0); cond_init(&buffer->less, USYNC_PROCESS, 0); cond_init(&buffer->more, USYNC_PROCESS, 0); if (fork() == 0) consumer_driver(buffer); else producer_driver(buffer); } void producer_driver(buffer_t *b) { int item; while (1) { item = getchar(); if (item == EOF) { producer(b, `\0'); break; } else producer(b, (char)item); } } void consumer_driver(buffer_t *b) { char item; while (1) { if ((item = consumer(b)) == '\0') break; putchar(item); } }
A child process is created to run the consumer. The parent runs the producer.
Prior to the Solaris 10 release, Solaris threads and POSIX threads defined the behavior of fork() differently. See Process Creation: exec and exit Issues for a thorough discussion of fork() issues.
Solaris libthread supported both fork() and fork1(). The fork() call has “fork-all” semantics. fork() duplicated everything in the process, including threads and LWPs, creating a true clone of the parent. The fork1() call created a clone that had only one thread. The process state and address space are duplicated, but only the calling thread was cloned.
POSIX libpthread supported only fork(), which has the same semantics as fork1() in Solaris threads.
Whether fork() has “fork-all” semantics or “fork-one” semantics was dependent on which library is used. Link with -lthread to assign “fork-all” semantics to fork(). Link with -lpthread to assign “fork-one” semantics to fork().
Effective with the Solaris 10 release, fork() has the same semantics in both Solaris threads and POSIX threads. More specifically, fork1() semantics replicate only the caller. A new function, forkall() , is provided for those applications that require replicate-all semantics.
See Compiling and Linking a Multithreaded Program for more details.