Guide to DECthreads

int
pthread_key_delete (
pthread_key_t key);

ARGUMENTS

key

Context key to be deleted.

DESCRIPTION

This routine deletes a thread-specific data key previously returned by pthread_key_create(). The thread-specific data values associated with key need not be NULL at the time this routine is called. The application must free any application storage or perform any cleanup actions for data structures related to the deleted key or associated thread-specific data in any threads. This cleanup can be done either before or after this routine call. Do not attempt to use the key after calling this routine; this results in unpredictable behavior.

No destructor functions are invoked by this routine. Any destructor functions that may have been associated with key, shall no longer be called upon thread exit. pthread_key_delete() can be called from within destructor functions.

Associated Routines

• pthread_getspecific()
• pthread_key_create()
• pthread_exit()

Delivers a signal to a specified target thread.

This routine is for Digital UNIX systems only.

Syntax

pthread_kill(
thread ,
sig );

Argument	Data Type	Access
thread	opaque pthread_t	read
sig	integer	read

int
pthread_kill (
pthread_t thread,
int sig);

ARGUMENTS

thread

Thread to receive a signal request.

sig

A signal request. If sig is zero, error checking is performed, but no signal is sent.

DESCRIPTION

This routine sends a signal to the specified target thread thread. Any signal defined to stop, continue, or terminate will stop or terminate the process, even though it may be handled by the target thread. For example, SIGTERM terminates all threads in the process, even though it may be handled by the target thread.

The name of the "kill" routine is sometimes misleading, because many signals do not terminate a thread.

The various signals are as follows:

	SIGHUP	SIGPIPE	SIGTTIN
	SIGINT	SIGALRM	SIGTTOU
	SIGQUIT	SIGTERM	SIGIO
	SIGTRAP	SIGUSR1	SIGXCPU
	SIGABRT	SIGSYS	SIGXFSZ
	SIGEMT	SIGURG	SIGVTALRM
	SIGFPE	SIGSTOP	SIGPROF
	SIGKILL	SIGTSTP	SIGINFO
	SIGBUS	SIGCONT	SIGUSR1
	SIGSEGV	SIGCHLD	SIGUSR2

If this routine does not execute successfully, no signal is sent.

Locks the DECthreads global mutex if the global mutex is unlocked. If the global mutex is locked by another thread, causes the thread to wait for the global mutex to become available.

Syntax

pthread_lock_global_np( );

int
pthread_lock_global_np (void);

ARGUMENTS

None

DESCRIPTION

This routine locks the DECthreads global mutex. If the global mutex is currently held by another thread when a thread calls this routine, the thread waits for the global mutex to become available.

The thread that has locked the global mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the global mutex in the locked state and with the current thread as the global mutex's current owner.

Use the global mutex when calling a library package that is not designed to run in a multithreaded environment. Unless the documentation for a library function specifically states that it is thread-safe, assume that it is not compatible; in other words, assume it is nonreentrant.

The global mutex is one lock. Any code that calls any function that is not known to be reentrant uses the same lock. This prevents problems resulting from dependencies among threads that call library functions and those functions calling other functions, and so on.

The global mutex is a recursive mutex. A thread that has locked the global mutex can relock it without deadlocking. The locking thread must call pthread_unlock_global_np() as many times as it called this routine, to allow another thread to lock the global mutex.

Associated Routines

• pthread_unlock_global_np()

Destroys a mutex.

Syntax

pthread_mutex_destroy(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write

int
pthread_mutex_destroy (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

The mutex to be destroyed.

DESCRIPTION

This routine destroys a mutex by uninitializing it, and should be called when a mutex object is no longer referenced. After this routine is called, DECthreads may reclaim internal storage used by the mutex object.

It is safe to destroy an initialized mutex that is unlocked. However, it is illegal to destroy a locked mutex.

The results of this routine are unpredictable if the mutex object specified in the mutex argument does not currently exist, or is not initialized.

Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EBUSY]	An attempt is made to destroy the object referenced by mutex while it is locked or referenced.
[EINVAL]	The value specified by mutex is invalid.

Associated Routines

• pthread_mutex_init()
• pthread_mutex_lock()
• pthread_mutex_trylock()
• pthread_mutex_unlock()

Initializes a mutex with attributes specified by the attr argument.

Syntax

pthread_mutex_init(
mutex ,
attr );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	write
attr	opaque pthread_mutexattr_t	read

int
pthread_mutex_init (
pthread_mutex_t *mutex,
const pthread_mutexattr_t *attr);

ARGUMENTS

mutex

Mutex created.

attr

Mutex attributes object to be used in initializing the characteristics of the created mutex.

DESCRIPTION

This routine initializes a mutex with the attributes specified by the attr argument. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.

The mutex is initialized and set to the unlocked state. If attr is set to NULL, the default mutex attributes are used. The pthread_mutexattr_settype_np() routine can be used to specify the type of mutex that is created (normal, recursive, or errorcheck).

See Chapter 2 for more information about mutex usage.

A mutex is a resource of the process, not part of any particular thread. A mutex is neither destroyed nor unlocked automatically when any thread exits. Because mutexes are shared, they may be allocated in heap or static memory but not on a stack.

Use the PTHREAD_MUTEX_INITIALIZER macro to statically initialize a mutex without calling this routine. Statically initialized mutexes need not be destroyed using pthread_mutex_destroy(). Use this macro as follows:
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER

Only normal mutexes can be statically initialized.

Associated Routines

• pthread_mutexattr_init()
• pthread_mutexattr_gettype_np()
• pthread_mutexattr_settype_np()
• pthread_mutex_lock()
• pthread_mutex_trylock()
• pthread_mutex_unlock()

Locks an unlocked mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available.

Syntax

pthread_mutex_lock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
pthread_mutex_lock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Mutex to be locked.

DESCRIPTION

This routine locks a mutex with varying behavior as follows:

• If a normal mutex is specified, a deadlock can result if the current owner of a mutex calls this routine in an attempt to lock the mutex a second time. (The deadlock is not detected or reported.)
• If a recursive mutex was specified, the current owner of a mutex can relock the same mutex without blocking. The lock count is incremented for each recursive lock within the thread.
• If an errorcheck mutex was specified and the current owner tries to lock the mutex a second time, the [EDEADLK] error is reported. If the mutex is locked by another thread, the calling thread waits for the mutex to become available.

Use the pthread_mutexattr_settype_np() routine to set the type of the mutex to normal, recursive, or errorcheck. For more information about mutexes, see Chapter 2.

The thread that has locked a mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the calling thread as the mutex's current owner.

A recursive or errorcheck mutex records the identity of the thread that locks it, allowing debuggers to display this information. In most cases, normal mutexes do not record the thread identity.

Associated Routines

• pthread_mutexattr_settype_np()
• pthread_mutex_destroy()
• pthread_mutex_init()
• pthread_mutex_trylock()
• pthread_mutex_unlock()

Attempts to lock a mutex. If the mutex is already locked, the calling thread does not wait for the mutex to become available.

Syntax

pthread_mutex_trylock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
pthread_mutex_trylock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Mutex to be locked.

DESCRIPTION

This routine attempts to lock a mutex. When a thread calls this routine, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, zero (0) is returned and the calling thread becomes the mutex's current owner. If the specified mutex is locked when a thread calls this routine, the calling thread does not wait for the mutex to become available.

The behavior of this routine is as follows:

• If a normal or errorcheck mutex is locked by any thread (including the current thread) when this routine is called, [EBUSY] is returned and the thread does not wait to acquire the lock.
• If a normal or errorcheck mutex is not owned, a zero is returned and the mutex becomes locked.
• If a recursive mutex is owned by the current thread, a zero is returned and the mutex lock count is incremented. (To unlock a recursive mutex, each call to pthread_mutex_trylock() must be matched by a call to pthread_mutex_unlock().)

Use the pthread_mutexattr_settype_np() routine to set the mutex type attribute (normal, recursive, or errorcheck). For information about mutex types and their usage, see Chapter 2.

Associated Routines

• pthread_mutexattr_settype_np()
• pthread_mutex_destroy()
• pthread_mutex_init()
• pthread_mutex_lock()
• pthread_mutex_unlock()

Unlocks a mutex.

Syntax

pthread_mutex_unlock(
mutex );

Argument	Data Type	Access
mutex	opaque pthread_mutex_t	read

int
pthread_mutex_unlock (
pthread_mutex_t *mutex);

ARGUMENTS

mutex

Mutex to be unlocked.

DESCRIPTION

This routine unlocks a mutex.

The following describes the varied behavior of this routine:

• When an owner unlocks a recursive mutex that it owns, the lock count is decremented. The mutex remains locked and owned until the lock count reaches zero (0). When the lock count reaches zero, or for any other type of mutex, the mutex becomes unlocked with no current owner.
• If a normal or errorcheck mutex is owned by the current thread, it is unlocked.
• If an errorcheck mutex is not locked or is locked by another thread, [EPERM] is returned. A normal mutex may also return [EPERM], but this is not guaranteed.

If one or more threads are waiting to lock the specified mutex, and the mutex becomes unlocked, this routine causes one thread to unblock and try to acquire the mutex. The scheduling policy is used to determine which thread to unblock. For the SCHED_FIFO and SCHED_RR policies, a blocked thread is chosen in priority order, using first-in/first-out within priorities. Note that the mutex may not be acquired by the awakened thread, if any other running thread attempts to lock the mutex first.

On Digital UNIX, if a signal is delivered to a thread waiting for a mutex, upon return from the signal handler, the thread resumes waiting for the mutex as if it was not interrupted.

Associated Routines

• pthread_mutexattr_settype_np()
• pthread_mutex_destroy()
• pthread_mutex_init()
• pthread_mutex_lock()
• pthread_mutex_trylock()
• pthread_unlock_global_np()

Destroys a mutex attributes object.

Syntax

pthread_mutexattr_destroy(
attr );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write

int
pthread_mutexattr_destroy (
pthread_mutexattr_t *attr);

ARGUMENTS

attr

Attributes object to be destroyed.

DESCRIPTION

This routine destroys a mutex attributes object---that is, the object becomes uninitialized. Call this routine when a mutex attributes object is no longer needed.

After this routine is called, DECthreads may reclaim the storage used by the mutex attributes object. Mutexes that were created using this attributes object are not affected by the destruction of the mutex attributes object.

The results of calling this routine are unpredictable, if the attributes object specified in the attr argument does not exist.

Associated Routines

• pthread_mutexattr_init()

Obtains the mutex type attribute used when a mutex is created.

Syntax

pthread_mutexattr_gettype_np(
attr ,
type );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	read
type	integer	write

int
pthread_mutexattr_gettype_np (
const pthread_mutexattr_t *attr,
int *type);

ARGUMENTS

attr

Mutex attributes object whose mutex type is obtained.

type

Receives the value of the mutex type attribute. The type argument specifies the type of mutex that is created. Valid values are:

• PTHREAD_MUTEX_NORMAL_NP (default)
• PTHREAD_MUTEX_RECURSIVE_NP
• PTHREAD_MUTEX_ERRORCHECK_NP

DESCRIPTION

This routine obtains the mutex type attribute that is used when a mutex is created. See the pthread_mutexattr_settype_np() description for information about mutex type attributes.

If an error condition occurs, this routine returns an integer value indicating the type of the error. Possible return values are as follows:

Return	Description
0	Successful completion.
[EINVAL]	The value specified by attr is invalid.

Associated Routines

• pthread_mutexattr_init()
• pthread_mutexattr_settype_np()
• pthread_mutex_init()

Initializes a mutex attributes object.

Syntax

pthread_mutexattr_init(
attr );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write

int
pthread_mutexattr_init (
pthread_mutexattr_t *attr);

ARGUMENTS

attr

Mutex attributes object to be initialized.

DESCRIPTION

This routine initializes a mutex attributes object (attr), which is used to specify the attributes of mutexes when they are created. The mutex attributes object is initialized with the default value for all of the attributes defined by DECthreads.

When a mutex attributes object is used to initialize a mutex, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like additional arguments to object creation. Changing individual attributes or destroying the attributes object does not affect any objects that were previously created using the attributes object.

Associated Routines

• pthread_create()
• pthread_mutexattr_gettype_np()
• pthread_mutexattr_settype_np()
• pthread_mutex_init()

Specifies the mutex type attribute that is used when a mutex is created.

Syntax

pthread_mutexattr_settype_np(
attr ,
type );

Argument	Data Type	Access
attr	opaque pthread_mutexattr_t	write
type	integer	read

  6493P011.HTM
  OSSG Documentation
  22-NOV-1996 13:20:12.72

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal