Guide to DECthreads

int
pthread_mutexattr_settype_np (
pthread_mutexattr_t *attr,
int type);

ARGUMENTS

attr

Mutex attributes object whose mutex type attribute is modified.

type

New value for 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 sets the mutex type attribute that is used to determine which type of mutex is created on a call to pthread_mutex_init(). See Section 2.4.1 for information on the types of mutexes.

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.
[EINVAL]	The value specified by attr or type is invalid.
[ESRCH]	The value specified by attr does not refer to an existing mutex attributes object.

Associated Routines

• pthread_mutexattr_init()
• pthread_mutexattr_gettype_np()
• pthread_mutex_init()

Calls an initialization routine that is executed by a single thread, once.

Syntax

pthread_once(
once _control,
init _routine );

Argument	Data Type	Access
once_control	opaque pthread_once_t	modify
init_routine	procedure	read

int
pthread_once (
pthread_once_t *once_control,
void (*init_routine) (void));

ARGUMENTS

once_control

Address of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique pthread_once_t record.

init_routine

Address of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated once_control are passed to pthread_once().

DESCRIPTION

The first call to this routine by any thread in a process with a given once_control will call the init_routine with no arguments. Subsequent calls to pthread_once() with the same once_control will not call the init_routine. On return from pthread_once(), it is guaranteed that the initialization routine has completed.

For example, a mutex or a per-thread context key must be created exactly once. Calling pthread_once() ensures that the initialization is serialized across multiple threads. Other threads that reach the same point in the code would be delayed until the first thread is finished.

---

Note

If you specify an init_routine that directly or indirectly results in a recursive call to pthread_once() and that specifies the same init_block argument, the recursive call may result in a deadlock.

---

To initialize the once_control record, your program can zero out the entire structure, or you can use the PTHREAD_ONCE_INIT macro, which is defined in the pthread.h header file, to statically initialize that structure. If using PTHREAD_ONCE_INIT, declare the once_control record as follows:

pthread_once_t  once_control = PTHREAD_ONCE_INIT; 

Note that it is often easier to simply lock a statically initialized mutex, check a control flag, and perform necessary initialization (in-line) rather than using pthread_once(). For example, you can code an "init" routine that begins with the following basic logic:

  init() 
  { 
   static pthread_mutex_t    mutex = PTHREAD_MUTEX_INIT; 
   static int                flag = FALSE; 
   
   pthread_mutex_lock(&mutex); 
   if(!flag) 
     { 
      flag = TRUE; 
      /* initialize code */ 
     } 
   pthread_mutex_unlock(&mutex); 
  } 
   

Obtains the identifier of the current thread.

Syntax

pthread_self( );

pthread_t
pthread_self (void);

ARGUMENTS

None

DESCRIPTION

This routine allows a thread to obtain its own thread identifier.

This value becomes meaningless after the thread is destroyed.

Associated Routines

• pthread_cancel()
• pthread_create()
• pthread_detach()
• pthread_exit()
• pthread_join()
• pthread_kill()
• pthread_sigmask()

Sets the calling thread's cancelability state.

Syntax

pthread_setcancelstate(
state ,
oldstate );

Argument	Data Type	Access
state	integer	read
oldstate	integer	write

int
pthread_setcancelstate (
int state,
int *oldstate );

ARGUMENTS

state

State of general cancelability to set for the calling thread. The following are valid cancel state values:

• PTHREAD_CANCEL_ENABLE
• PTHREAD_CANCEL_DISABLE

oldstate

Previous cancelability state.

DESCRIPTION

This routine sets the calling thread's cancelability state and returns the previous cancelability state in oldstate.

When cancelability state is set to PTHREAD_CANCEL_DISABLE, a cancelation request cannot be delivered to the thread, even if a cancelable routine is called or asynchronous cancelability type is enabled.

When a thread is created, its default cancelability state is PTHREAD_CANCEL_ENABLE.

Possible Problems When Disabling Cancelability

The most important use of thread cancelation is to ensure that indefinite wait operations are terminated. For example, a thread that waits on some network connection, which may take days to respond (or may never respond), should be made cancelable.

When a thread's cancelability is disabled, no routine in that thread is cancelable. As a result, the user is unable to cancel the operation performed by that thread. When disabling cancelability, be sure that no long waits can occur or that it is necessary for other reasons to defer cancelation requests around that particular region of code.

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.
[EINVAL]	The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

Associated Routines

• pthread_cancel()
• pthread_setcanceltype()
• pthread_testcancel()

Sets the calling thread's cancelability type.

Syntax

pthread_setcanceltype(
type ,
oldtype );

Argument	Data Type	Access
type	integer	read
oldtype	integer	write

int
pthread_setcanceltype (
int type,
int *oldtype);

ARGUMENTS

type

The cancelability type to set for the calling thread. The following are valid values:

• PTHREAD_CANCEL_DEFERRED
• PTHREAD_CANCEL_ASYNCHRONOUS

oldtype

Returns the previous cancelability type.

DESCRIPTION

This routine sets the cancelability type and returns the previous type in location oldtype.

When a thread's cancelability state is set to PTHREAD_CANCEL_DISABLE, (see pthread_setcancelstate()), a cancelation request cannot be delivered to that thread, even if a cancelable routine is called or asynchronous cancelability type is enabled.

When the cancelability state is set to PTHREAD_CANCEL_ENABLE, cancelability depends on the thread's cancelability type, as follows:

• If the thread's cancelability state is PTHREAD_CANCEL_ENABLE and the thread's cancelability type is set to PTHREAD_CANCEL_DEFERRED, the thread can only receive a cancelation request at a cancelation point (including condition waits, thread joins, and calls to pthread_testcancel()).
• If the thread's cancelability state is PTHREAD_CANCEL_ENABLE and its cancelability type is PTHREAD_CANCEL_ASYNCHRONOUS, the thread can be canceled at any point in its execution.

When a thread is created, the default cancelability type is
PTHREAD_CANCEL_DEFERRED.

---

Warning

If the asynchronous cancelability type is set, do not call any routine unless it is explicitly documented as "safe for asynchronous cancelation." Note that none of the general run-time libraries and none of the DECthreads libraries are safe for asynchronous cancelation except for pthread_setcanceltype() and pthread_setcancelstate().

Use asynchronous cancelability only when you have a compute-bound section of code that carries no state and makes no routine calls.

---

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.
[EINVAL]	The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_AYNCHRONOUS.

Associated Routines

• pthread_cancel()
• pthread_setcancelstate()
• pthread_testcancel()

Changes a thread's scheduling policy and scheduling parameters.

Syntax

pthread_setschedparam(
thread ,
policy ,
param );

Argument	Data Type	Access
thread	opaque pthread_t	read
policy	integer	read
param	struct sched_param	read

int
pthread_setschedparam (
pthread_t thread,
int policy,
const struct sched_param *param);

ARGUMENTS

thread

Thread whose scheduling policy and parameters are to be changed.

policy

New scheduling policy value for the thread specified in thread. The following are valid values:

• SCHED_BG_NP
• SCHED_FG_NP
• SCHED_FIFO
• SCHED_OTHER
• SCHED_RR

See Section 2.3.2.2 for a description of thread scheduling policies.

param

New values of the scheduling parameters associated with the scheduling policy for the thread specified in thread. Valid values for the sched_priority field of a sched_param structure depend on the chosen scheduling policy and fall within one of the following ranges.

Low	High
PRI_FIFO_MIN	PRI_FIFO_MAX
PRI_RR_MIN	PRI_RR_MAX
PRI_OTHER_MIN	PRI_OTHER_MAX
PRI_FG_MIN_NP	PRI_FG_MAX_NP
PRI_BG_MIN_NP	PRI_BG_MAX_NP

Calculate the priority using the appropriate symbols such as PRI_FIFO_MIN or PRI_FIFO_MAX. Avoid using numeric constants as priorities. (Section 2.3.6 describes how to specify priorities between the minimum and maximum values.)

DESCRIPTION

This routine changes both the current scheduling policy and associated scheduling parameters of the thread specified by thread to the policy and associated parameters provided in policy and param, respectively.

All currently implemented DECthreads scheduling policies have one scheduling parameter called sched_priority. For the policy you choose, you must specify an appropriate value in the sched_priority field of the sched_param structure.

Changing the scheduling policy or priority, or both, of a thread can cause it to start executing or to be preempted by another thread. A thread changes its own scheduling policy and priority by using the handle returned by pthread_self().

This routine differs from pthread_attr_setschedpolicy() and
pthread_attr_setschedparam(), in that those routines set the scheduling policy and parameter attributes that are used to establish the scheduling priority and scheduling policy of a new thread when it is created. However, this routine changes the scheduling policy and parameters of an existing thread.

Associated Routines

• pthread_attr_getschedparam()
• pthread_attr_setschedpolicy()
• pthread_create()
• pthread_self()
• sched_yield()

Sets the thread-specific data value associated with the specified key for the calling thread.

Syntax

pthread_setspecific(
key ,
value );

Argument	Data Type	Access
key	opaque pthread_key_t	read
value	void *	read

int
pthread_setspecific (
pthread_key_t key,
const void *value);

ARGUMENTS

key

Thread-specific key that identifies the thread-specific data to receive value. This key value must be obtained from pthread_key_create().

value

New thread-specific data value to associate with the specified key for the calling thread.

DESCRIPTION

This routine sets the thread-specific data value associated with the specified key for the current thread. If a value is defined for the key in this thread (the current value is not NULL), the new value is substituted for it. The key is obtained by a previous call to pthread_key_create().

Different threads can bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that are reserved for use by the calling thread.

Do not call this routine from a thread-specific data destructor function.

Note that although the type for value (void*) implies an address, the type is being used as a "universal scalar type." DECthreads simply stores value for later retrieval.

Associated Routines

• pthread_getspecific()
• pthread_key_create()
• pthread_key_delete()

Examine or change the calling thread's signal mask.

This routine is for Digital UNIX systems only.

Syntax

pthread_sigmask(
how ,
set ,
oset );

Argument	Data Type	Access
how	integer	read
set	sigset_t	read
oset	sigset_t	write

int
pthread_sigmask (
int how,
const sigset_t *set,
sigset_t *oset);

ARGUMENTS

how

Indicates the manner in which the set of masked signals is changed. The optional values are as follows:

	SIG_BLOCK	The resulting set is the union of the current set and the signal set pointed to by the set argument.
	SIG_UNBLOCK	The resulting set is the intersection of the current set and the complement of the signal set pointed to by the set argument.
	SIG_SETMASK	The resulting set is the signal set pointed to by the set argument.

set

Specifies the signal set by pointing to a set of signals used to change the blocked set. If this set value is NULL, the how argument is ignored and the process signal mask is unchanged.

oset

Receives the value of the current signal mask (unless this value is NULL).

DESCRIPTION

This routine examines or changes the calling thread's signal mask. Typically, you use the SIG_BLOCK option for the how value to block signals during a critical section of code, and then use this routine's SIG_SETMASK option to restore the mask to the previous value returned by the previous call to the pthread_sigmask() function.

If there are any unblocked signals pending after a call to this routine, at least one of those signals will be delivered before this routine returns.

This routine does not allow the SIGKILL or SIGSTOP signals to be blocked. If a program attempts to block one of these signals, pthread_sigmask() gives no indication of the error.

Requests delivery of any pending cancelation request to the calling thread.

Syntax

pthread_testcancel( );

void
pthread_testcancel (void);

ARGUMENTS

None

DESCRIPTION

This routine requests delivery of a pending cancelation request to the calling thread. Thus, calling this routine creates a cancelation point within the calling thread. The cancelation request is delivered only if a request is pending for the calling thread and the calling thread's cancelability state is enabled. (A thread disables delivery of cancelation requests to itself by calling pthread_setcancelstate().)

When called within very long loops, this routine ensures that a pending cancelation request is noticed by the calling thread within a reasonable amount of time.

Associated Routines

• pthread_setcancelstate()

Unlocks the DECthreads global mutex.

Syntax

pthread_unlock_global_np( );

int
pthread_unlock_global_np (void);

ARGUMENTS

None

DESCRIPTION

This routine unlocks the DECthreads global mutex. Since the global mutex is recursive, the unlock will occur when each call to pthread_lock_global_np() has been matched by a call to this routine. For example, if you called pthread_lock_global_np() three times, pthread_unlock_global_np() unlocks the global mutex when you call it the third time.

If no threads are waiting for the global mutex, it becomes unlocked with no current owner. If one or more threads are waiting to lock the global mutex, this routine causes one thread to unblock and try to acquire the mutex. The scheduling policy is used to determine which thread is awakened. For the policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities.

Associated Routines

• pthread_lock_global_np()

Yields execution to another thread.

Syntax

sched_yield( );

int sched_yield (
void);

ARGUMENTS

None

DESCRIPTION

In conformance with the IEEE POSIX.1b-1995 standard, the sched_yield() function causes the calling thread to yield execution to another thread. It is useful when a thread running under the SCHED_FIFO scheduling policy must allow another thread at the same priority to run. The thread that is interrupted by sched_yield() goes to the end of the queue for its priority.

If no other thread is runnable at the priority of the calling thread, the calling thread continues to run.

Threads with higher priority are allowed to preempt the calling thread, so the sched_yield() function has no effect on the scheduling of higher- or lower-priority threads.

The sched_yield() routine takes no arguments. No special privileges are needed to use the sched_yield() function.

Associated Routines

• pthread_attr_setschedparam()
• pthread_setschedparam()
• pthread_getscheduler()

  6493P012.HTM
  OSSG Documentation
  22-NOV-1996 13:20:14.49

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal