JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Multithreaded Programming Guide     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

1.  Covering Multithreading Basics

2.  Basic Threads Programming

3.  Thread Attributes

4.  Programming with Synchronization Objects

5.  Programming With the Oracle Solaris Software

6.  Programming With Oracle Solaris Threads

Comparing APIs for Oracle Solaris Threads and POSIX Threads

Major API Differences

Function Comparison Table

Unique Oracle Solaris Threads Functions

Suspending Thread Execution

thr_suspend Syntax

thr_suspend Return Values

Continuing a Suspended Thread

thr_continue Syntax

thr_continue Return Values

Similar Synchronization Functions: Read-Write Locks

Initialize a Read-Write Lock

rwlock_init Syntax

Initializing Read-Write Locks With Intraprocess Scope

Initializing Read-Write Locks With Interprocess Scope

rwlock_init Return Values

Acquiring a Read Lock

rw_rdlock Syntax

rw_rdlock Return Values

Trying to Acquire a Read Lock

rw_tryrdlock Syntax

rw_tryrdlock Return Values

Acquiring a Write Lock

rw_wrlock Syntax

rw_wrlock Return Values

Trying to Acquire a Write Lock

rw_trywrlock Syntax

rw_trywrlock Return Values

Unlock a Read-Write Lock

rw_unlock Syntax

rw_unlock Return Values

Destroying the Read-Write Lock State

rwlock_destroy Syntax

rwlock_destroy Return Values

Similar Oracle Solaris Threads Functions

Creating a Thread

thr_create Syntax

thr_create Return Values

Getting the Minimal Stack Size

thr_min_stack Syntax

thr_min_stack Return Values

Acquiring the Thread Identifier

thr_self Syntax

thr_self Return Values

Yield Thread Execution

thr_yield Syntax

thr_yield Return Values

Send a Signal to a Thread

thr_kill Syntax

thr_kill Return Values

Access the Signal Mask of the Calling Thread

thr_sigsetmask Syntax

thr_sigsetmask Return Values

Terminate a Thread

thr_exit Syntax

thr_exit Return Values

Wait for Thread Termination

thr_join Syntax

thr_join, Join Specific

thr_join, Join Any

thr_join Return Values

Creating a Thread-Specific Data Key

thr_keycreate Syntax

thr_keycreate Return Values

Setting the Thread-Specific Data Value

thr_setspecific Syntax

thr_setspecific Return Values

Getting the Thread-Specific Data Value

thr_getspecific Syntax

thr_getspecific Return Values

Set the Thread Priority

thr_setprio Syntax

thr_setprio Return Values

Get the Thread Priority

thr_getprio Syntax

thr_getprio Return Values

Similar Synchronization Functions: Mutual Exclusion Locks

Initialize a Mutex

mutex_init(3C) Syntax

Mutexes With Intraprocess Scope

Mutexes With Interprocess Scope

Mutexes With Interprocess Scope-Robust

mutex_init Return Values

Destroy a Mutex

mutex_destroy Syntax

mutex_destroy Return Values

Acquiring a Mutex

mutex_lock Syntax

mutex_lock Return Values

Releasing a Mutex

mutex_unlock Syntax

mutex_unlock Return Values

Trying to Acquire a Mutex

mutex_trylock Syntax

mutex_trylock Return Values

Similar Synchronization Functions: Condition Variables

Initialize a Condition Variable

cond_init Syntax

Condition Variables With Intraprocess Scope

Condition Variables With Interprocess Scope

cond_init Return Values

Destroying a Condition Variable

cond_destroy Syntax

cond_destroy Return Values

Waiting for a Condition

cond_wait Syntax

cond_wait Return Values

Wait for an Absolute Time

cond_timedwait Syntax

cond_timedwait Return Values

Waiting for a Time Interval

cond_reltimedwait Syntax

cond_reltimedwait Return Values

Unblock One Thread

cond_signal Syntax

cond_signal Return Values

Unblock All Threads

cond_broadcast Syntax

cond_broadcast Return Values

Similar Synchronization Functions: Semaphores

Initialize a Semaphore

sema_init Syntax

Semaphores With Intraprocess Scope

Semaphores With Interprocess Scope

sema_init Return Values

Increment a Semaphore

sema_post Syntax

sema_post Return Values

Block on a Semaphore Count

sema_wait Syntax

sema_wait Return Values

Decrement a Semaphore Count

sema_trywait Syntax

sema_trywait Return Values

Destroy the Semaphore State

sema_destroy(3C) Syntax

sema_destroy(3C) Return Values

Synchronizing Across Process Boundaries

Example of Producer and Consumer Problem

Special Issues for fork() and Oracle Solaris Threads

7.  Safe and Unsafe Interfaces

8.  Compiling and Debugging

9.  Programming Guidelines

A.  Extended Example: A Thread Pool Implementation

Index

Similar Synchronization Functions: Semaphores

Semaphore operations are the same in both the Oracle Solaris Operating Environment and the POSIX environment. The function name changed from sema_ in the Oracle Solaris Operating Environment to sem_ in pthreads. This section discusses the following topics:

Initialize a Semaphore

Use sema_init(3C) to initialize the semaphore variable pointed to by sp by count amount.

sema_init Syntax

#include <thread.h>

int sema_init(sema_t *sp, unsigned int count, int type,
    void *arg);

type can be one of the following values:

Multiple threads must not initialize the same semaphore simultaneously. A semaphore must not be reinitialized while other threads might be using the semaphore.

Semaphores With Intraprocess Scope
#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); 
Semaphores With Interprocess Scope
#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 Return Values

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.

Increment a Semaphore

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.

sema_post Syntax

#include <thread.h>

int sema_post(sema_t *sp);

sema_post Return Values

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.

Block on a Semaphore Count

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.

sema_wait Syntax

#include <thread.h>

int sema_wait(sema_t *sp);

sema_wait Return Values

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.

Decrement a Semaphore Count

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

sema_trywait Syntax

#include <thread.h>

int sema_trywait(sema_t *sp);

sema_trywait Return Values

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.

Destroy the Semaphore State

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.

sema_destroy(3C) Syntax

#include <thread.h>

int sema_destroy(sema_t *sp);

sema_destroy(3C) Return Values

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.