Transportation Administration System
Snoezelen Pillows for Dementia
Begeleiders voor gehandicapten
Laat uw hond het jaarlijkse vuurwerk overwinnen
Betuweroute en Kunst
Hey Vos! Je eigen naam@vos.net emailadres?
Kunst in huis? Nicole Karrèr maakt echt bijzonder mooie dingen
Kunst in huis? Netty Franssen maakt ook bijzonder mooie dingen1 DECthreads
DECthreads is Digital's multithreading run-time library package. DECthreads offers access to library routines via several interfaces. DECthreads offers two primary interfaces: o The PTHREAD multithreading interface is Digital's implementation of the IEEE POSIX 1003.1c-1995 standard. Use this interface to build portable, multithreaded applications. o The Digital proprietary TIS interface offers routines that provide "thread-independent services." These routines allow a program to perform (or a library to offer) thread- safe processing that requires synchronization, but without requiring the use of threads. A thread is a single, sequential flow of control within a program. Use threads to improve a program's performance-that is, its throughput, computational speed, responsiveness, or some combination. Multiple threads are useful in a multiprocessor system, where a program's threads can run concurrently on separate processors. On single-processor systems, multiple threads can also improve a program's performance by permitting the overlap of input, output, or other slow operations with computational operations. For more information see the Guide to DECthreads documentation. 2 PTHREAD_routines Routines that comprise the DECthreads multithreading PTHREAD interface are based on the IEEE POSIX 1003.1c-1995 standard. The global errno variable is not used by these routines. To indicate errors, the PTHREAD routines return integer values indicating the type of error. Routine names ending with the _np suffix denote that the routine is not portable; that is, the routine might not be available in implementations of POSIX 1003.1c-1995 other than DECthreads. See the Guide to DECthreads documentation for more information. 3 pthread_attr_destroy Destroys a thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_destroy ( pthread_attr_t *attr); 4 Arguments attr Thread attributes object to be destroyed. 4 Description This routine destroys a thread attributes object. Call this routine when a thread attributes object will no longer be referenced. Threads that were created using this thread attributes object are not affected by the destruction of the thread attributes object. The results of calling this routine are unpredictable if the value specified by the attr argument refers to a thread attributes object that does not exist. 4 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 is invalid. 4 Associated_Routines pthread_attr_init() pthread_create() 3 pthread_attr_getdetachstate Obtains the detachstate attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_getdetachstate ( const pthread_attr_t *attr, int *detachstate); 4 Arguments attr Thread attributes object whose detachstate attribute is obtained. detachstate Receives the value of the detachstate attribute. 4 Description This routine obtains the detachstate attribute of a thread attributes object. This attribute specifies whether threads created using the specified thread attributes object are created in detachedstate. On successful completion, this routine returns a zero and the detached state attribute is set in detachstate. A value of PTHREAD_CREATE_JOINABLE indicates the thread is not detached, and a value of PTHREAD_CREATE_DETACHED indicates the thread is detached. See the pthread_attr_setdetachstate() description for information about the detachstate attribute. 4 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 does not refer to an existing thread attributes object. 4 Associated_Routines pthread_attr_init() pthread_attr_setdetachstate() 3 pthread_attr_getguardsize_np Obtains the guardsize attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_getguardsize_np ( const pthread_attr_t *attr size_t *guardsize); 4 Arguments attr Thread attributes object whose guardsize attribute is obtained. guardsize Receives the value for the guardsize attribute. The guardsize argument specifies the minimum size in bytes of the guard area for a thread. 4 Description This routine obtains the minimum size in bytes of the guard area for the stack of a thread that is created using the attributes object specified by the attr argument. A guard area helps to detect stack overflows by preventing memory access beyond the thread's stack. Large guard areas are necessary when threads might allocate large structures on the stack. 4 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 is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_setstacksize() pthread_attr_setguardsize_np() pthread_create() 3 pthread_attr_getinheritsched Obtains the inherit scheduling attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_getinheritsched ( const pthread_attr_t *attr int *inheritsched); 4 Arguments attr Thread attributes object whose inherit scheduling attribute is obtained. inheritsched Receives the value of the inherit scheduling attribute. Refer to the description of the pthread_attr_setinheritsched() function for valid values. 4 Description This routine obtains the value of the inherit scheduling attribute from the specified thread attributes object. The inherit scheduling attribute specifies whether threads created using the attributes object inherit the scheduling attributes of the creating thread, or use the scheduling attributes stored in the attributes object that is passed to pthread_create(). 4 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 is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_setinheritsched() pthread_create() 3 pthread_attr_getschedparam Obtains the scheduling parameters for an attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_getschedparam ( const pthread_attr_t *attr, struct sched_param *param); 4 Arguments attr Thread attributes object of the scheduling policy attribute whose parameters are obtained. param Receives the values of scheduling parameters for the scheduling policy attribute of the attributes object specified by the attr argument. Refer to the description of the pthread_attr_ setschedparam() function for valid parameters and their values. 4 Description This routine obtains the scheduling parameters associated with the scheduling policy attribute of the specified thread attributes object. 4 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 is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_setschedparam() pthread_create() 3 pthread_attr_getschedpolicy Obtains the scheduling policy attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_getschedpolicy ( const pthread_attr_t *attr, int *policy); 4 Arguments attr Thread attributes object whose scheduling policy attribute is obtained. policy Receives the value of the scheduling policy attribute. Refer to the description of the pthread_attr_setschedpolicy() function for valid values. 4 Description This routine obtains the value of the scheduling policy attribute of the specified thread attributes object. The scheduling policy attribute defines the scheduling policy for threads created using the attributes object. 4 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 is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_setschedpolicy() pthread_create() 3 pthread_attr_getstacksize Obtains the stacksize attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_getstacksize ( const pthread_attr_t *attr, size_t *stacksize); 4 Arguments attr Thread attributes object whose stacksize attribute is obtained. stacksize Receives the value for the stacksize attribute. 4 Description This routine obtains the stacksize attribute of the thread attributes object specified in attr. 4 Return_Values On successful completion, this routine returns a zero (0) and the stacksize value in the stacksize variable. 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 is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_setstacksize() pthread_create() 3 pthread_attr_init Initializes a thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_init ( pthread_attr_t *attr); 4 Arguments attr Thread attributes object to be initialized. 4 Description This routine initializes a thread attributes object that is used to specify the attributes of threads when they are created. The attributes object created by this routine is used only in calls to pthread_create(). The following routines change the initialized individual attributes of a thread attributes object: pthread_attr_setdetachstate() pthread_attr_setguardsize_np() pthread_attr_setinheritsched() pthread_attr_setschedparam() pthread_attr_setschedpolicy() pthread_attr_setstacksize() The individual attributes (internal fields) of the attributes object are initialized to default values. The default values of each attribute are discussed in the descriptions of the thread attribute setting routines listed above. When an attributes object is used to create a thread, the values of the individual attributes determine the characteristics of the new thread. Attributes objects act as additional arguments to thread creation. Changing individual attributes does not affect any threads that were previously created using the attributes object. You can use a single attributes object in multiple calls to pthread_create(), from any thread. If multiple threads might change attributes in a shared attributes object, the application code must protect the integrity of the attributes object by using a mutex. When you set the scheduling policy or scheduling parameters, or both, in an attributes object, you must disable scheduling inheritance if you want the scheduling attributes you set to be used at thread creation. To disable scheduling inheritance use the pthread_attr_setinheritsched() routine, specifying the value PTHREAD_EXPLICIT_SCHED for the inherit argument, before calling pthread_create(). 4 Return_Values If an error condition occurs, the thread attributes object cannot be used and 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 is invalid. [ENOMEM] Insufficient memory exists to initialize the thread attributes object. 4 Associated_Routines pthread_attr_destroy() pthread_attr_setdetachstate() pthread_attr_setguardsize_np() pthread_attr_setinheritsched() pthread_attr_setschedparam() pthread_attr_setschedpolicy() pthread_attr_setstacksize() pthread_setguardsize_np() pthread_create() 3 pthread_attr_setdetachstate Changes the detachstate attribute in the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_setdetachstate ( pthread_attr_t *attr, int detachstate); 4 Arguments attr Thread attributes object to be modified. detachstate New value for the detachstate attribute. Valid values are as follows: PTHREAD_CREATE_ This is the default value. Threads are JOINABLE created in "undetached" state. PTHREAD_CREATE_ The created thread is detached immediately, DETACHED before it begins running. 4 Description This routine changes the detachstate attribute in the thread creation attributes. This attribute specifies whether the threads created using the specified thread attributes object are created in a detached state or not. A value of PTHREAD_CREATE_JOINABLE indicates the thread is not detached, and a value of THREAD_ CREATE_DETACHED indicates the thread is detached. PTHREAD_CREATE_ JOINABLE is the default value. You cannot use the thread handle (the value of type pthread_t that is returned by pthread_create() for a detached thread. This means that you cannot cancel the thread with pthread_cancel(). You also cannot use pthread_join() to wait for the thread to complete or to retrieve the thread's return status. When a thread that has not been detached completes execution, DECthreads will retain the state of that thread to allow another thread to join with it. If the thread is detached before it completes, DECthreads is free to immediately reclaim the thread's storage and resources. Failing to detach threads that have completed execution can result in wasting resources, so threads should be detached as soon as the program is done with them. If there is no need to use the thread's handle after creation, create the thread initially detached. 4 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 the detachstate argument is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_getdetachstate() pthread_create() pthread_join() 3 pthread_attr_setguardsize_np Changes the guardsize attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_setguardsize_np ( pthread_attr_t *attr, size_t guardsize); 4 Arguments attr Threads attributes object to be modified. guardsize New value for the guardsize attribute. The guardsize argument specifies the minimum size (in bytes) of the guard area for the stack of a thread. 4 Description This routine sets the minimum size (in bytes) of the guard area for the stack of a thread that is created using the attributes object specified by the attr argument. A guard area helps to detect stack overflows by preventing memory access beyond the thread's stack. Large guard areas are necessary when threads might allocate large structures on the stack. The default value is platform dependent, but will always be at least one "hardware protection unit" (at least one page). 4 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 is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_getguardsize_np() 3 pthread_attr_setinheritsched Changes the inherit scheduling attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_setinheritsched ( pthread_attr_t *attr, int inheritsched); 4 Arguments attr Thread attributes object to be modified. inheritsched New value for the inherit scheduling attribute. Valid values are as follows: PTHREAD_INHERIT_ The created thread inherits the SCHED scheduling policy and associated scheduling attributes of the thread calling pthread_create(). Any scheduling attributes in the attributes object specified by the pthread_create() attr argument are ignored during thread creation. This is the default value. PTHREAD_EXPLICIT_ The scheduling policy and associated SCHED scheduling attributes of the created thread are set to the corresponding values from the attribute object specified by the pthread_create() attr argument. 4 Description This routine changes the inherit scheduling attribute of thread creation. The inherit scheduling attribute specifies whether threads created using the specified attributes object inherit the scheduling attributes of the creating thread, or use the scheduling attributes stored in the attributes object specified by the pthread_create() attr argument. The first thread in an application has a scheduling policy of SCHED_OTHER. See the pthread_attr_setschedparam() and pthread_ attr_setschedpolicy() routines for more information on valid priority values and valid scheduling policy values, respectively. Inheriting scheduling attributes (instead of using the scheduling attributes stored in the attributes object) is useful when a thread is creating several helper threads-threads that are intended to work closely with the creating thread to cooperatively solve the same problem. For example, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling thread. 4 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] One or both of the values specified by inherit or by attr is invalid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 4 Associated_Routines pthread_attr_init() pthread_attr_getinheritsched() pthread_attr_setschedpolicy() pthread_attr_setschedparam() pthread_create() 3 pthread_attr_setschedparam Changes the values of the parameters associated with a scheduling policy of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_setschedparam ( pthread_attr_t *attr, const struct sched_param *param); 4 Arguments attr Thread attributes object for the scheduling policy attribute whose parameters are to be set. param A structure containing new values for scheduling parameters associated with the scheduling policy attribute defined for the specified thread attributes object. NOTE DECthreads provides only the sched_priority scheduling parameter. It allows you to specify the scheduling priority. See below for information about this scheduling parameter. 4 Description This routine sets the scheduling parameters associated with the scheduling policy attribute for the thread attributes object specified by the attr argument. Scheduling Priority Use the sched_priority field of a sched_param structure to set a thread's execution priority. The effect of the scheduling priority you assign depends on the scheduling policy specified for the attributes object specified by the attr argument. By default, a created thread inherits the priority of the thread calling pthread_create(). To specify a priority using this routine, scheduling inheritance must be disabled at the time the thread is created. Call pthread_attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument before calling pthread_create(). An application specifies priority only to express the urgency of executing the thread relative to other threads. Do not use priority to control mutual exclusion when accessing shared data. With a sufficient number of processors executing, all ready threads, regardless of priority, execute simultaneously. Valid values of the sched_priority scheduling parameter depend on the chosen policy and fall within one of the following ranges: Policy Low High SCHED_FIFO PRI_FIFO_MIN PRI_FIFO_MAX SCHED_RR PRI_RR_MIN PRI_RR_MAX SCHED_OTHER PRI_OTHER_MIN PRI_OTHER_MAX SCHED_FG_NP PRI_FG_MIN_NP PRI_FG_MAX_NP SCHED_BG_NP PRI_BG_MIN_NP PRI_BG_MAX_NP The default priority is the midpoint between PRI_OTHER_MIN and PRI_OTHER_MAX for the SCHED_OTHER scheduling policy. 4 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 param is invalid. [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 4 Associated_Routines pthread_attr_init() pthread_attr_getschedparam() pthread_attr_setinheritsched() pthread_attr_setschedpolicy() pthread_create() sched_yield() 3 pthread_attr_setschedpolicy Changes the scheduling policy attribute of the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_setschedpolicy ( pthread_attr_t *attr, int policy); 4 Arguments attr Thread attributes object to be modified. policy New value for the scheduling policy attribute. Valid values are as follows: SCHED_BG_NP SCHED_FG_NP (also known as SCHED_OTHER) SCHED_FIFO SCHED_RR SCHED_OTHER is the default value. 4 Description This routine sets the scheduling policy of a thread that is created using the attributes object specified by the attr argument. The default value of the scheduling attribute is SCHED_ OTHER. By default, a created thread inherits the policy of the thread calling pthread_create(). To specify a policy using this routine, scheduling inheritance must be disabled at the time the thread is created. Call pthread_attr_setinheritsched() and specify the value PTHREAD_EXPLICIT_SCHED for the inherit argument before calling pthread_create(). Never attempt to use scheduling as a mechanism for synchronization. 4 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 policy is invalid. 4 Associated_Routines pthread_attr_init() pthread_attr_getschedpolicy() pthread_attr_setinheritsched() pthread_attr_setschedparam() pthread_create() 3 pthread_attr_setstacksize Changes the stacksize attribute in the specified thread attributes object. 4 C_Binding #include <pthread.h> int pthread_attr_setstacksize ( pthread_attr_t *attr, size_t stacksize); 4 Arguments attr Threads attributes object to be modified. stacksize New value for the stacksize attribute of the specified thread attributes object. The stacksize argument must be greater than or equal to PTHREAD_STACK_MIN. PTHREAD_STACK_MIN specifies the minimum size in bytes of stack needed for a thread. 4 Description This routine sets the stacksize attribute in the attr object. Use this routine to adjust the size of the writable area of the stack for threads that will be created. A thread's stack is fixed at the time of thread creation. Only the initial thread can dynamically extend its stack. Many compilers do not check for stack overflow. Ensure that your thread stack is large enough for anything that you call from the thread. 4 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 is invalid, or the value specified by stacksize is less than PTHREAD_STACK_MIN or exceeds a DECthreads-imposed limit. 4 Associated_Routines pthread_attr_init() pthread_attr_getstacksize() pthread_create() 3 pthread_cancel Allows a thread to request a thread to terminate execution. 4 C_Binding #include <pthread.h> int pthread_cancel ( pthread_t thread); 4 Arguments thread Thread that receives a cancelation request. 4 Description This routine sends a cancelation request to the specified target thread. A cancelation request is a mechanism by which a calling thread requests the target thread to terminate as quickly as possible. Issuing a cancelation request does not guarantee that the target thread will receive or handle the request. When the cancelation request is acted on, all active cleanup handlers for the target thread are called. When the last cleanup handler returns, the thread-specific data destructor functions are called for each thread-specific data key with a destructor and for which the target thread has a non-NULL value. Finally, the target thread is terminated. Note that cancelation of the target thread runs asychronously with respect to the calling thread returning from pthread_ cancel(). The target thread's cancelability state and type determine when or if the cancellation takes place, as follows: 1. The target thread can delay cancellation during critical operations by setting its cancelability state to PTHREAD_ CANCEL_DISABLE. 2. Because of communication delays, the calling thread can only rely on the fact that a cancelation request will eventually become pending in the target thread (provided that the target thread does not terminate beforehand). 3. The calling thread has no guarantee that a pending cancelation request will be delivered, because delivery is controlled by the target thread. When a cancelation request is delivered to a thread, termination processing is similar to pthread_exit(). For more information about thread termination, see the Thread Termination section of pthread_create(). This routine is preferred in implementing an Ada abort statement and any other language- or software-defined construct for requesting thread cancelation. The results of this routine are unpredictable, if the value specified in thread refers to a thread that does not currently exist. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The specified thread is invalid. [ESRCH] The thread argument does not specify an existing thread. 4 Associated_Routines pthread_cleanup_pop() pthread_cleanup_push() pthread_create() pthread_exit() pthread_join() pthread_setcancelstate() pthread_setcanceltype() pthread_testcancel() 3 pthread_cleanup_pop (Macro) Removes the cleanup handler and optionally executes it. 4 C_Binding #include <pthread.h> void pthread_cleanup_pop( int execute); 4 Arguments execute Integer that specifies whether the cleanup routine specified in the matching call to pthread_cleanup_push() is executed. A nonzero value will cause the routine to be executed. This routine can be used to clean up from a block of code whether exited by cancellation or normal completion. 4 Description This routine removes the cleanup routine and executes it if the value specified in execute is nonzero. This routine and pthread_cleanup_push() are implemented as macros and must appear as statements and in pairs within the same lexical scope. You can think of the pthread_cleanup_push() macro as expanding to a string whose first character is a left brace ({) and pthread_cleanup_pop() as expanding to a string containing the corresponding right brace (}). 4 Return_Values None 4 Associated_Routines pthread_cancel() pthread_cleanup_push() pthread_create() pthread_exit() 3 pthread_cleanup_push (Macro) Establishes a cleanup handler to be executed when the thread exits or is canceled. 4 C_Binding #include <phtread.h> void pthread_cleanup_push( void (*routine)(void *), void *arg); 4 Arguments routine Routine executed as the cleanup handler. arg Argument executed with the cleanup routine. 4 Description This routine pushes the specified routine onto the calling thread's cleanup stack. The cleanup routine is popped from the stack and executed with the arg argument when any of the following actions occur: o The thread calls pthread_exit(). o The thread is canceled. o An exception is raised (while the cleanup routine in is effect) and results in an unwind through the scope of the pthread_cleanup_push() and pthread_cleanup_pop() pair. o The thread calls pthread_cleanup_pop() and specifies a nonzero value for the execute argument. This routine and pthread_cleanup_pop() are implemented as macros and must appear as statements and in pairs within the same lexical scope. You can think of the pthread_cleanup_push() macro as expanding to a string whose first character is a left brace ({) and pthread_cleanup_pop() as expanding to a string containing the corresponding right brace (}). 4 Return_Values None 4 Associated_Routines pthread_cancel() pthread_cleanup_pop() pthread_create() pthread_exit() pthread_testcancel() 3 pthread_cond_broadcast Wakes all threads that are waiting on a condition variable. 4 C_Binding #include <pthread.h> int pthread_cond_broadcast ( pthread_cond_t *cond); 4 Arguments cond Condition variable upon which the threads (to be awakened) are waiting. 4 Description This routine unblocks all threads waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, so that it might be possible for one or more waiting threads to proceed. The threads that are unblocked shall contend for the mutex according to the scheduling policy (if applicable). If only one of the threads waiting on a condition variable may be able to proceed, but any single thread can proceed, then use pthread_cond_signal() instead. Whether the associated mutex is locked or unlocked, you can still call this routine. However, if predictable scheduling behavior is required, then that mutex should then be locked by the thread calling the pthread_cond_broadcast() routine. If no threads are waiting on the specified condition variable, then this routine takes no action. The broadcast does not propagate to the next condition variable wait. 4 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 cond is invalid. 4 Associated_Routines pthread_cond_destroy() pthread_cond_init() pthread_cond_signal() pthread_cond_timedwait() pthread_cond_wait() 3 pthread_cond_destroy Destroys a condition variable. 4 C_Binding #include <pthread.h> int pthread_cond_destroy ( pthread_cond_t *cond); 4 Arguments cond Condition variable to destroy. 4 Description This routine destroys the condition variable specified by cond. This effectively uninitializes the condition variable. You call this routine when a condition variable will no longer be referenced. Destroying a condition variable allows DECthreads to reclaim internal memory associated with the condition variable. It is safe to destroy an initialized condition variable upon which no threads are currently blocked. Attempting to destroy a condition variable upon which other threads are blocked results in unpredictable behavior. The results of this routine are unpredictable, if the condition variable specified in cond does not exist or is not initialized. 4 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 cond is invalid. [EBUSY] The object being referenced by cond is being referenced by another thread that is currently executing a pthread_cond_wait() or pthread_cond_timedwait() on the condition variable specified in cond. 4 Associated_Routines pthread_cond_broadcast() pthread_cond_init() pthread_cond_signal() pthread_cond_timedwait() pthread_cond_wait() 3 pthread_cond_init Initializes a condition variable. 4 C_Binding #include <pthread.h> int pthread_cond_init ( pthread_cond_t *cond, const pthread_condattr_t *attr); 4 Arguments cond Condition variable to initialize. attr Condition variable attributes object that defines the characteristics of the condition variable to initialize. 4 Description This routine initializes the condition variable cond with attributes referenced by attr. If attr is NULL, the default condition variable attributes are used. A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to shared data; a condition variable allows threads to wait for that data to enter a defined state. Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread terminates. Use the DECthreads macro PTHREAD_COND_INITIALIZER to initialize statically allocated condition variables to the default condition variable attributes. To call this macro, enter: pthread_cond_t condition = PTHREAD_COND_INITIALIZER When statically initialized, a condition variable should not also be using pthread_cond_init(). Also, a statically initialized condition variable need not be destroyed using pthread_cond_ destroy(). Under certain circumstances it may be impossible to wait upon a statically initialized condition variable when the process virtual address space (or some other memory limit) is nearly exhausted. In such a case pthread_cond_wait() or pthread_cond_ timedwait() may return [ENOMEM]. You can avoid this possibility by initializing critical condition variables with pthread_cond_ init(). 4 Return_Values If an error condition occurs, this routine returns an integer value indicating the type of error, the condition variable is not initialized, and the contents of cond are undefined. Possible return values are as follows: Return Description 0 Successful completion. [EAGAIN] The system lacks the necessary resources to initialize another condition variable, or The system-imposed limit on the total number of condition variables under execution by a single user is exceeded. [EBUSY] The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable. [EINVAL] The value specified by attr is invalid. [ENOMEM] Insufficient memory exists to initialize the condition variable. 4 Associated_Routines pthread_cond_broadcast() pthread_cond_destroy() pthread_cond_signal() pthread_cond_timedwait() pthread_cond_wait() 3 pthread_cond_signal Wakes at least one thread that is waiting on a condition variable. 4 C_Binding #include <pthread.h> int pthread_cond_signal ( pthread_cond_t *cond); 4 Arguments cond Condition variable to be signaled. 4 Description This routine unblocks at least one thread waiting on the specified condition variable cond. Calling this routine implies that data guarded by the associated mutex has changed, so that it might be possible for one of the waiting threads to proceed. In general, only one will be released. If no threads are waiting on the specified condition variable, then this routine takes no action. The signal does not propagate to the next condition variable wait. This routine should be called when any thread waiting on the specified condition variable might find its predicate true, but only one thread should proceed. If more than one thread can proceed, or if any thread would not be able to proceed, then you must use pthread_cond_broadcast(). The scheduling policy determines which thread is awakened. For policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first-out (FIFO) within priorities. You can call this routine even when the associated mutex is locked. However, if predictable scheduling behavior is required, then that mutex should be locked by the thread calling pthread_ cond_signal(). 4 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 cond is invalid. 4 Associated_Routines pthread_cond_broadcast() pthread_cond_destroy() pthread_cond_init() pthread_cond_timedwait() pthread_cond_wait() 3 pthread_cond_signal_int_np Wakes one thread that is waiting on a condition variable (called from interrupt level only). 4 C_Binding #include <pthread.h> int pthread_cond_signal_int_np( pthread_cond_t *cond); 4 Arguments cond Condition variable to be signaled. 4 Description This routine wakes one thread waiting on a condition variable. It can only be called from a software interrupt handler routine (such as from a Digital UNIX signal handler or OpenVMS AST). Calling this routine implies that it might be possible for a single waiting thread to proceed. The scheduling policies of the waiting threads determine which thread is awakened. For policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order, using first-in/first- out (FIFO) within priorities. This routine does not cause a thread blocked on a condition variable to resume execution immediately. A thread resumes execution at some time after the interrupt handler returns. You can call this routine regardless of whether the associated mutex is locked. Never try to lock a mutex from an interrupt handler. NOTE This routine allows you to signal a thread from a software interrupt handler. Do not call this routine from noninterrupt code. To signal a thread from the normal noninterrupt level, use pthread_cond_signal(). 4 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 cond is invalid. 4 Associated_Routines pthread_cond_wait() pthread_cond_timedwait() pthread_cond_signal() pthread_cond_broadcast() 3 pthread_cond_timedwait Causes a thread to wait for a condition variable to be signaled or broadcasted such that it will awake after a specified period of time. 4 C_Binding #include <pthread.h> int pthread_cond_timedwait ( pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime); 4 Arguments cond Condition variable that a thread waits on. mutex Mutex associated with the condition variable specified in cond. abstime Absolute time at which the wait expires, if the condition has not been signaled or broadcasted. See the pthread_get_expiration_np() routine, which is used to obtain a value for this argument. The abstime argument is specified in Universal Coordinated Time (UTC). In the UTC-based model, time is represented as seconds since the Epoch. The Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1st, 1970 UTC. Seconds since the Epoch is a value interpreted as the number of seconds between a specified time and the Epoch. 4 Description This routine causes a thread to wait until one of the following occurs: o The specified condition variable is signaled or broadcasted. o The current system clock time is greater than or equal to the time specified by the abstime argument. This routine is identical to pthread_cond_wait(), except that this routine can return before a condition variable is signaled or broadcasted; specifically, when a specified time expires. For more information, see the pthread_cond_wait() description. This routine atomically releases the mutex and causes the calling thread to wait on the condition. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the timer expires or when the wait is satisfied as a result of some thread calling pthread_cond_ signal() or pthread_cond_broadcast(), the mutex is reacquired before returning to the caller. If the current time equals or exceeds the expiration time, this routine returns immediately, without releasing the mutex or causing the current thread to wait. Your code should check the return status whenever this routine returns and take the appropriate action. Otherwise, waiting on the condition variable can become a nonblocking loop. Call this routine after you lock the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The value specified by cond, mutex, or abstime is invalid, or: Different mutexes are supplied for concurrent pthread_cond_timedwait() operations or pthread_cond_ wait() operations on the same condition variable, or: The mutex was not owned by the current thread at the time of the call. [ETIMEDOUT] The time specified by abstime expired. [ENOMEM] DECthreads cannot acquire memory needed to block using a statically initialized condition variable. 4 Associated_Routines pthread_cond_broadcast() pthread_cond_destroy() pthread_cond_init() pthread_cond_signal() pthread_cond_wait() pthread_get_expiration_np() 3 pthread_cond_wait Causes a thread to wait for a condition variable to be signaled or broadcasted. 4 C_Binding #include <pthread.h> int pthread_cond_wait ( pthread_cond_t *cond, pthread_mutex_t *mutex); 4 Arguments cond Condition variable that a thread waits on. mutex Mutex associated with the condition variable specified in cond. 4 Description This routine causes a thread to wait for a condition variable to be signaled or broadcasted. Each condition corresponds to one or more Boolean relations, called a predicate, based on shared data. The calling thread waits for the data to reach a particular state for the predicate to become true. However, the return from this routine does not imply anything about the value of the predicate and it should be reevaluated upon return. Call this routine after you have locked the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex. This routine atomically releases the mutex and causes the calling thread to wait on the condition. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the wait is satisfied as a result of some thread calling pthread_cond_signal() or pthread_cond_ broadcast(), the mutex is reacquired before returning to the caller. A thread that changes the state of storage protected by the mutex in such a way that a predicate associated with a condition variable might now be true, must call either pthread_cond_ signal() or pthread_cond_broadcast() for that condition variable. If neither call is made, any thread waiting on the condition variable continues to wait. This routine might (with low probability) return when the condition variable has not been signaled or broadcasted. When this occurs, the mutex is reacquired before the routine returns. To handle this type of situation, enclose this routine in a loop that checks the predicate. The loop provides documentation of your intent and protects against these spurious wakeups, while also allowing correct behavior even if another thread consumes the desired state before the awakened thread runs. It is illegal for threads to wait on the same condition variable by specifying different mutexes. 4 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 cond or mutex is invalid, or: Different mutexes are supplied for concurrent pthread_cond_wait() or pthread_cond_timedwait() operations on the same condition variable, or: The mutex was not owned by the current thread at the time of the call. [ENOMEM] DECthreads cannot acquire memory needed to block using a statically initialized condition variable. 4 Associated_Routines pthread_cond_broadcast() pthread_cond_destroy() pthread_cond_init() pthread_cond_signal() pthread_cond_timedwait() 3 pthread_condattr_destroy Destroys a condition variable attributes object. 4 C_Binding #include <pthread.h> int pthread_condattr_destroy ( pthread_condattr_t *attr); 4 Arguments attr Condition variable attributes object to be destroyed. 4 Description This routine destroys a condition variable attributes object-that is, the object becomes uninitialized. Condition variables that were created using this attributes object are not affected by the deletion of the condition variable attributes object. After calling this routine, the results of using attr in a call to any routine (other than pthread_condattr_init()) are unpredictable. 4 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 attributes object specified by attr is invalid. 4 Associated_Routines pthread_condattr_init() 3 pthread_condattr_init Initializes a condition variable attributes object that can be used to specify the attributes of condition variables when they are created. 4 C_Binding #include <pthread.h> int pthread_condattr_init ( pthread_condattr_t *attr); 4 Arguments attr Condition variable attributes object to initialize. 4 Description This routine initializes the condition variable attributes object (attr) that is used to specify the attributes of condition variables when they are initialized. The condition variable attributes object is initialized with the default attribute values. When a condition variable attributes object is used to initialize a condition variable, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like additional arguments to object initialization. Changing individual attributes does not affect objects that were previously initialized using the attributes object. 4 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. [ENOMEM] Insufficient memory exists to initialize the condition variable attributes object. 4 Associated_Routines pthread_condattr_destroy() pthread_cond_init() 3 pthread_create Creates a thread. 4 C_Binding #include <pthread.h> int pthread_create ( pthread_t *thread, const pthread_attr_t *attr, void * (*start_routine) (void *), void *arg); 4 Arguments thread Thread object created. attr Thread attributes object that defines the characteristics of the thread being created. If you specify NULL, default attributes are used. start_routine Function executed as the new thread's start routine. arg Address value copied and passed to the thread's start routine. 4 Description This routine creates a thread. A thread is a single, sequential flow of control within a program. It is the active execution of a designated routine, including any nested routine invocations. Successful execution of this routine includes the following actions: o An internal thread object is created to describe and control the thread. The thread object includes a Thread Environment Block (TEB) that programs can use (with care). o The thread argument receives an identifier for the new thread. o An executable thread is created with attributes specified by the attr argument (or with default attributes if NULL is specified). Thread Creation A thread is created in the ready state to begin executing the function specified by the start_routine argument. The new thread may execute immediately. The newly created thread may preempt its creator, depending on scheduling policy and priority. The thread identifier specified in pthread_create() will be written before the new thread executes. The new thread's scheduling policy and priority are, by default, inherited from the creating thread-the scheduling policy and priority set in the attributes object are ignored. To create a thread using the scheduling policy and priority set in the attributes object, you must first disable the inherit scheduling attribute by calling pthread_attr_setinheritsched() before calling pthread_create(). The thread exists until it is both terminated and detached. A thread is detached when created if the detach state attribute of its thread object is set to PTHREAD_CREATE_DETACHED. It is also detached after any thread returns successfully from calling pthread_detach() or pthread_join() for the thread. Termination is explained in the next section (see Thread Termination). The caller of pthread_create() can synchronize with the newly created thread through the use of the pthread_join() routine, or any other mutexes or condition variables they agree to use. On Digital UNIX, the signal state of the new thread is initialized as follows: 1. The signal mask is inherited from the creating thread. 2. The set of signals pending for the new thread is empty. If pthread_create() fails, no new thread is created, and the contents of the location referenced by thread are undefined. Thread Termination A thread terminates when one of the following events occurs: o The thread returns from its start routine. o An exception is raised (or re-raised) in the thread during execution, and the exception is not handled. o The thread calls the pthread_exit() routine. o The thread is canceled. DECthreads performs the following actions when a thread terminates: 1. DECthreads writes a return value (if one is available) into the terminated thread's thread object: o If the thread has been canceled, DECthreads writes the value PTHREAD_CANCELED into the thread's thread object. o If the thread terminated by returning from its start routine, DECthreads copies the return value from the start routine (if one is available) into the thread's thread object. Alternatively, if the thread explictly called pthread_exit(), DECthreads stores the value received in the value_ptr argument (from pthread_exit()) into the thread's thread object. Another thread can obtain this return value by joining with the terminated thread (using pthread_join()). NOTE If the thread terminated by returning from its start routine normally and the start routine does not provide a return value, then the results obtained by joining with that thread are unpredictable. 2. If the termination results from a cancelation, a call to pthread_exit(), or an unhandled exception, DECthreads calls, in turn, each cleanup handler that this thread declared (using pthread_cleanup_push()) and that is not yet removed (using pthread_cleanup_pop()). (DECthreads also transfers control to any appropriate CATCH, CATCH_ALL, or FINALY blocks .) DECthreads calls the terminated thread's most recently pushed cleanup handler first. For C++ programmers: at normal exit from a thread, your program must call the appropriate destructor functions, just as if an exception has been raised. 3. To exit the terminated thread due to ... o ... a call to pthread_exit(), DECthreads raises the pthread_exit_e exception. o ... cancelation, DECthreads raises the pthread_cancel_e exception. Your program can use the DECthreads exception package to operate on the generated exception. (In particular, note that the practice of using CATCH handlers in place of pthread_ cleanup_push() is not portable.) 4. For each of the terminated thread's thread-specific data keys that has a non-NULL value: o DECthreads sets the thread's value for the corresponding key to NULL. o In turn, DECthreads calls each thread-specific data destructor function in this multithreaded process's list of destructors. DECthreads repeats this step until all thread-specific data values in the thread are NULL, or for up to a number of iterations equal to PTHREAD_DESTRUCTOR_ITERATIONS. This destroys all thread-specific data associated with the terminated thread. 5. DECthreads awakens the thread (if there is one) that is currently joined with the terminated thread. That is, DECthreads awakens the thread that is waiting in a call to pthread_join(). 6. If the thread is already detached, DECthreads destroys its thread object. Otherwise, the thread continues to exist until detached or joined. 4 Return_Values If an error condition occurs, no thread is created, the contents of thread are undefined, and this routine returns an integer value indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EAGAIN] The system lacks the necessary resources to create another thread, or the system-imposed limit on the total number of threads under execution by a single user is exceeded. [EINVAL] The value specified by attr is invalid. [ENOMEM] Insufficient enough memory exists to create a thread. [EPERM] The caller does not have the appropriate permission to create a thread with the specified attributes. 4 Associated_Routines pthread_atfork() pthread_attr_destroy() pthread_attr_init() pthread_attr_setdetachstate() pthread_attr_setinheritsched() pthread_attr_setschedparam() pthread_attr_setschedpolicy() pthread_attr_setstacksize() pthread_cancel() pthread_detach() pthread_exit() pthread_join() 3 pthread_debug Invokes the DECthreads internal debugger. 4 C_Binding #include <pthread.h> void pthread_debug (void); 4 Arguments None 4 Description This routine invokes the DECthreads internal debugger as a callable function. It takes no arguments and does not return a value. It enters the internal debugger parsing loop. Type exit to return to the program. To pass a list of debugging commands to DECthreads, call pthread_ debug_cmd(). 4 Return_Values None 4 Associated_Routines pthread_debug_cmd() 3 pthread_debug_cmd Passes a list of pthread_debug() commands to DECthreads. 4 C_Binding #include <pthread.h> pthreadDbgStatus_t pthread_debug_cmd ( char *cmd); 4 Arguments cmd pthread_debug() command string to pass to DECthreads debug. Null- terminated string, commands separated by semicolons. 4 Description This routine passes a list of debugging commands to DECthreads. Each command (separated by a semicolon) is executed in sequence. Any output is written to standard output. This routine returns the status of the last specified operation in the command string when the final command (or Exit command) is executed. The following are two examples of listing commands in a call to this routine: pthread_debug_cmd("thread -b; mu -lq; cond -wq"); pthread_debug_cmd("att"); To invoke the DECthreads debugger for interactive commands, call pthread_debug(). 4 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 Command successful [PTHREAD_DBG_QUIT] (1) Last command was quit or exit [PTHREAD_DBG_NONESEL] No objects selected (for example, thread (2) -br) [PTHREAD_DBG_ Alternate success SUCCESSPEND] (3) [PTHREAD_DBG_NOPRIV] No privilege for command (-1) [PTHREAD_DBG_INVPARAM] Invalid parameter on command (-2) [PTHREAD_DBG_INVSEQ] Invalid object sequence number given (-3) [PTHREAD_DBG_ Inconsistent state for operation INCONSTATE] (-4) [PTHREAD_DBG_CORRUPT] Unable to complete due to internal (-5) corruption [PTHREAD_DBG_INVOPTION] Invalid command options (-6) [PTHREAD_DBG_NOARG] Missing command argument (-7) [PTHREAD_DBG_INVADDR] Invalid address (-8) [PTHREAD_DBG_INVCMD] Invalid command (-9) [PTHREAD_DBG_NULLCMD] No command given (-10) [PTHREAD_DBG_CONFLICT] Conflicting options (-11) [PTHREAD_DBG_UNIMPL] Unimplemented feature (-12) 4 Associated_Routines pthread_debug() 3 pthread_delay_np Causes a thread to delay execution. 4 C_Binding #include <pthread.h> int pthread_delay_np ( const struct timespec *interval); 4 Arguments interval Number of seconds and nanoseconds to delay execution. The value specified for each must be greater than or equal to zero. 4 Description This routine causes a thread to delay execution for a specific period of time. This period ends at the current time plus the specified interval. The routine will not return before the end of the period is reached, but may return an arbitrary amount of time after the period has gone by. This can be due to system load, thread priorities, and system timer granularity. Specifying an interval of zero (0) seconds and zero (0) nanoseconds is allowed and can be used to force the thread to give up the processor or to deliver a pending cancel. The struct timespec structure contains the following two fields: o tv_sec is an integer number of seconds. o tv_nsec is an integer number of nanoseconds. 4 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 interval is invalid. 3 pthread_detach Marks a thread object for deletion. 4 C_Binding #include <pthread.h> int pthread_detach ( pthread_t thread); 4 Arguments thread Thread object being marked for deletion. 4 Description A call to this routine indicates that storage for the specified thread can be reclaimed when the thread terminates. This includes storage for the thread argument's return value, as well as the thread object. If thread has not terminated when this routine is called, this routine does not cause it to terminate. When a thread object is no longer referenced, call this routine. The results of this routine are unpredictable if the value of thread refers to a thread object that does not exist. A thread can be created "pre-detached" using its thread object's detach state attribute. The pthread_join() function also detaches the target thread when pthread_join() returns successfully. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The value specified by thread does not refer to a joinable thread. [ESRCH] The value specified by thread cannot be found. 4 Associated_Routines pthread_cancel() pthread_create() pthread_exit() pthread_join() 3 pthread_equal Compares one thread identifier to another thread identifier. 4 C_Binding #include <pthread.h> int pthread_equal ( pthread_t t1, pthread_t t2); 4 Arguments t1 The first thread identifier to be compared. t2 The second thread identifier to be compared. 4 Description This routine compares one thread identifier to another thread identifier. If either t1 or t2 are not valid thread identifiers, this routine's behavior is undefined. 4 Return_Values Possible return values are as follows: Return Description 0 Values of t1 and t2 do not designate the same object. Non-zero Values of t1 and t2 designate the same object. 3 pthread_exit Terminates the calling thread. 4 C_Binding #include <pthread.h> void pthread_exit ( void *value_ptr); 4 Arguments value_ptr Value copied and returned to the caller of pthread_join(). Note that void * is used as a universal datatype, not as a pointer. DECthreads treats the value_ptr as a value and stores it to be returned by pthread_join(). 4 Description This routine terminates the calling thread and makes a status value (value_ptr) available to any thread that calls pthread_ join() and specifies the terminating thread. Any cleanup handlers that have been pushed and not yet popped from the stack, are popped in the reverse order that they were pushed and then executed. After all cleanup handlers have been executed, appropriate destructor functions shall be called in an unspecified order if the thread has any thread-specific data. Thread termination does not release any application-visible process resources, including, but not limited to mutexes and file descriptors, nor does it perform any process-level cleanup actions, including, but not limited to calling any atexit() routine that may exist. An implicit call to pthread_exit() is issued when a thread returns from the start routine that was used to create it. DECthreads writes the function's return value as the return value in the thread's thread object. The process exits when the last running thread calls pthread_exit(). After a thread has terminated, the result of access to local (that is, explicitly or implicitly declared auto) variables of the thread is undefined. So, references to local variables of the existing thread should not be used for the value_ptr argument of the pthread_exit() routine. 4 Return_Values None 4 Associated_Routines pthread_cancel() pthread_create() pthread_detach() pthread_join() 3 pthread_get_expiration_np Obtains a value representing a desired expiration time. 4 C_Binding #include <pthread.h> int pthread_get_expiration_np ( const struct timespec *delta, struct timespec *abstime); 4 Arguments delta Number of seconds and nanoseconds to add to the current system time. (The result is the time in the future.) This result will be placed in abstime. abstime Value representing the absolute expiration time. The absolute expiration time is obtained by adding delta to the current system time. The resulting abstime is in Universal Coordinated Time (UTC). This value should be passed to the pthread_cond_ timedwait() routine. 4 Description This routine adds a specified interval to the current absolute system time and returns a new absolute time. This new absolute time is used as the expiration time in a call to pthread_cond_ timedwait(). The struct timespec structure contains the following two fields: o tv.sec is an integer number of seconds. o tv.nsec is an integer number of nanoseconds. 4 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 delta is invalid. 4 Associated_Routines pthread_cond_timedwait() 3 pthread_getschedparam Obtains the current scheduling policy and scheduling parameters of a thread. 4 C_Binding #include <pthread.h> int pthread_getschedparam ( pthread_t thread, int *policy, struct sched_param *param); 4 Arguments thread Thread whose scheduling policy and parameters are obtained. policy Receives the value of the scheduling policy for the thread specified in thread. Refer to the description of the pthread_ setschedparam() function for valid parameters and their values. param Receives the value of the scheduling parameters for the thread specified in thread. Refer to the description of the pthread_ setschedparam() function for valid values. 4 Description This routine obtains both the current scheduling policy and associated scheduling parameters of the thread specified by thread. The priority value returned in the param structure is the value specified in attr at pthread_create() or by the most recent pthread_setschedparam() call affecting the target thread. This routine differs from pthread_attr_getschedpolicy() and pthread_attr_getschedparam(), in that those routines get the scheduling policy and parameter attributes that are used to establish the priority and scheduling policy of a new thread when it is created. This routine, however, obtains the scheduling policy and parameters of an existing thread. 4 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. [ESRCH] The value specified by thread does not refer to an existing thread. 4 Associated_Routines pthread_create() pthread_self() pthread_attr_getschedpolicy() pthread_attr_getschedparam() pthread_setschedparam() 3 pthread_getsequence_np Obtains the thread sequence number. 4 C_Binding #include <pthread.h> unsigned long pthread_getsequence_np ( pthread_t thread); 4 Arguments thread Thread whose sequence number is obtained. 4 Description This routine obtains the sequence number of the specified thread, which provides a unique identifier for each concurrent thread. Thread sequence numbers are never reused while a thread exists, but may be reused after the thread terminates. The debugger interfaces use this sequence number to identify each thread in commands and in display output. 4 Return_Values No errors are returned. The function pthread_getsequence_np() returns the sequence number of the specified thread. The result is undefined if thread is not a valid thread. 4 Associated_Routines pthread_create() 3 pthread_getspecific Obtains the thread-specific data associated with the specified key. 4 C_Binding #include <pthread.h> void *pthread_getspecific ( pthread_key_t key); 4 Arguments key Context key identifies the thread-specific data to be obtained. This key must be obtained from pthread_key_create(). 4 Description This routine obtains the thread-specific data associated with the specified key for the current thread. This function returns the value currently bound to the specified key on behalf of the calling thread. This routine may be called from a thread-specific data destructor function. 4 Return_Values No errors are returned. The function pthread_getspecific() returns the thread-specific data value associated with the given key. If no thread-specific data value is associated with key, or if key is not defined, then a NULL value is returned. 4 Associated_Routines pthread_key_create() pthread_setspecific() 3 pthread_join PTHREAD_JOIN32(), PTHREAD_JOIN64() The pthread_join32() and pthread_join64() forms are only valid in 64-pointer environments for OpenVMS Alpha. Ensure that your compiler provides 64-bit support prior to using pthread_join64(). Causes the calling thread to wait for the termination of a specified thread. 4 C_Binding #include <pthread.h> int pthread_join ( pthread_t thread, void **value_ptr); 4 Arguments thread Thread whose termination is awaited by the caller of this routine. value_ptr Return value of the terminating thread (when that thread calls pthread_exit() or returns.) 4 Description This routine suspends execution of the calling thread until the specified target thread thread terminates. A call to a pthread_join() routine returns after the target thread terminates. The pthread_join() routine is a deferred cancelation point: the target thread will not be detached if the thread blocked in pthread_join() is canceled. On return from a successful pthread_join() call with a non- NULL value_ptr argument, the value passed to pthread_exit() is returned in the location referenced by value_ptr, and the terminating thread is detached. If more than one thread attempts to join with a single thread, the results are unpredictable. If a thread calls this routine and specifies its own pthread_t, a deadlock can result. The pthread_join() (or pthread_detach()) function should eventually be called for every thread that is created with the detachstate attribute of its thread object set to PTHREAD_CREATE_ JOINABLE, so that storage associated with the thread may be reclaimed. For OpenVMS Alpha systems only, you can call pthread_join32() or pthread_join64() instead of pthread_join(). The pthread_join32() form returns a 32-bit void * value in the address to which value_ ptr points. The pthread_join64() form returns a 64-bit void * value. You can call either, or you can call pthread_join(). The pthread_join() routine is defined to pthread_join64() if you compile using /pointer_size=long. If you do not specify /pointer_ size, or if you specify /pointer_size=short, then pthread_join() is defined to be pthread_join32(). 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The value specified by thread does not refer to a joinable thread. [ESRCH] The value specified by thread does not refer to an existing thread ID. [EDEADLK] A deadlock was detected, or the value of thread specifies the calling thread. 4 Associated_Routines pthread_cancel() pthread_create() pthread_detach() pthread_exit() 3 pthread_key_create Generates a unique thread-specific data key. 4 C_Binding #include <pthread.h> int pthread_key_create ( pthread_key_t *key, void (*destructor)(void *)); 4 Arguments key The new thread-specific data key. destructor Procedure called to destroy a thread-specific data value associated with the created key when the thread terminates. Note, the argument to the destructor for the user-specified routine is the non-NULL value associated with a key. 4 Description This routine generates a unique, thread-specific data key that is visible to all threads in the process. The variable key provided by this routine is an opaque object used to locate thread-specific data. Although the same key value may be used by different threads, the values bound to the key by pthread_ setspecific() are maintained on a per-thread basis and persist for the life of the calling thread. DECthreads imposes a maximum number of thread-specific data keys, equal to the symbolic constant PTHREAD_KEYS_MAX. Thread-specific data allows client software to associate "static" information with the current thread. For example, where a routine declares a variable "static" in a single-threaded program, a multithreaded version of the program might create a thread- specific data key to store the same variable. This routine generates and returns a new key value. The key reserves a cell within each thread. Each call to this routine creates a new cell that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the pthread_once() description for more information.) When a thread terminates, its thread-specific data is automatically destroyed; however, the key remains unless destroyed by a call to pthread_key_delete(). An optional destructor function may be associated with each key. At thread exit, if a key has a non-NULL destructor pointer, and the thread has a non-NULL value associated with that key, the destructor function is called with the current associated value as its sole argument. The order in which thread-specific data destructors are called at thread termination is undefined. Before each destructor is called, the thread's value for the corresponding key is set to NULL. After the destructors have been called for all non-NULL values with associated destructors, if there are still some non-NULL values with associated destructors, then the process is repeated. If there are still non-NULL values for any key with a destructor after four repetitions of this process, DECthreads will terminate the thread. At this point, any key values that represent allocated heap will be lost. Note that this occurs only when a destructor performs some action that creates a new value for some key. Destructor code should attempt to avoid this sort of circularity. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EAGAIN] The system lacked the necessary resources to create another thread-specific data key, or the DECthreads- imposed limit on the total number of keys per process (PTHREAD_KEYS_MAX) has been exceeded. [ENOMEM] Insufficient memory exists to create the key. 4 Associated_Routines pthread_getspecific() pthread_setspecific() pthread_key_delete() pthread_once() 3 pthread_key_delete Deletes a thread-specific data key. 4 C_Binding #include <pthread.h> int pthread_key_delete ( pthread_key_t key); 4 Arguments key Context key to be deleted. 4 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. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The key value is an invalid argument. 4 Associated_Routines pthread_getspecific() pthread_key_create() pthread_exit() 3 pthread_lock_global_np 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. 4 C_Binding #include <pthread.h> int pthread_lock_global_np (void); 4 Arguments None 4 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. 4 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. 4 Associated_Routines pthread_unlock_global_np() 3 pthread_mutex_destroy Destroys a mutex. 4 C_Binding #include <pthread.h> int pthread_mutex_destroy ( pthread_mutex_t *mutex); 4 Arguments mutex The mutex to be destroyed. 4 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. 4 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. 4 Associated_Routines pthread_mutex_init() pthread_mutex_lock() pthread_mutex_trylock() pthread_mutex_unlock() 3 pthread_mutex_init Initializes a mutex with attributes specified by the attr argument. 4 C_Binding #include <pthread.h> int pthread_mutex_init ( pthread_mutex_t *mutex, const pthread_mutexattr_t *attr); 4 Arguments mutex Mutex created. attr Mutex attributes object to be used in initializing the characteristics of the created mutex. 4 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). 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. 4 Return_Values If an error condition occurs, this routine returns an integer value indicating the type of error, the mutex is not initialized, and the contents of mutex are undefined. Possible return values are as follows: Return Description 0 Successful completion. [EAGAIN] The system lacks the necessary resources to initialize a mutex. [ENOMEM] Insufficient memory exists to initialize the mutex. [EBUSY] The implementation has detected an attempt to reinitialize the mutex (a previously initialized, but not yet destroyed mutex). [EINVAL] The value specified by mutex is invalid. [EPERM] The caller does not have privileges to perform this operation. 4 Associated_Routines pthread_mutexattr_init() pthread_mutexattr_gettype_np() pthread_mutexattr_settype_np() pthread_mutex_lock() pthread_mutex_trylock() pthread_mutex_unlock() 3 pthread_mutex_lock Locks an unlocked mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available. 4 C_Binding #include <pthread.h> int pthread_mutex_lock ( pthread_mutex_t *mutex); 4 Arguments mutex Mutex to be locked. 4 Description This routine locks a mutex with varying behavior as follows: o 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.) o 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. o 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. 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. 4 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 mutex is invalid, or The mutex was created with the protocol attribute set to PTHREAD_PRIO_PROTECT and the calling thread's priority set higher than the mutex's current priority ceiling. [EDEADLK] A deadlock condition is detected. 4 Associated_Routines pthread_mutexattr_settype_np() pthread_mutex_destroy() pthread_mutex_init() pthread_mutex_trylock() pthread_mutex_unlock() 3 pthread_mutex_trylock Attempts to lock a mutex. If the mutex is already locked, the calling thread does not wait for the mutex to become available. 4 C_Binding #include <pthread.h> int pthread_mutex_trylock ( pthread_mutex_t *mutex); 4 Arguments mutex Mutex to be locked. 4 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: o 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. o If a normal or errorcheck mutex is not owned, a zero is returned and the mutex becomes locked. o 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). 4 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] The mutex is already locked; therefore, it was not acquired. [EINVAL] The value specified by mutex is invalid, or The mutex was created with the protocol attribute set to PTHREAD_PRIO_PROTECT and the calling thread's priority set higher than the mutex's current priority ceiling. 4 Associated_Routines pthread_mutexattr_settype_np() pthread_mutex_destroy() pthread_mutex_init() pthread_mutex_lock() pthread_mutex_unlock() 3 pthread_mutex_unlock Unlocks a mutex. 4 C_Binding #include <pthread.h> int pthread_mutex_unlock ( pthread_mutex_t *mutex); 4 Arguments mutex Mutex to be unlocked. 4 Description This routine unlocks a mutex. The following describes the varied behavior of this routine: o 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. o If a normal or errorcheck mutex is owned by the current thread, it is unlocked. o 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. 4 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 for mutex is invalid. [EPERM] The calling thread does not own the mutex. 4 Associated_Routines pthread_mutexattr_settype_np() pthread_mutex_destroy() pthread_mutex_init() pthread_mutex_lock() pthread_mutex_trylock() pthread_unlock_global_np() 3 pthread_mutexattr_destroy Destroys a mutex attributes object. 4 C_Binding #include <pthread.h> int pthread_mutexattr_destroy ( pthread_mutexattr_t *attr); 4 Arguments attr Attributes object to be destroyed. 4 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. 4 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 object value specified by attr is invalid. 4 Associated_Routines pthread_mutexattr_init() 3 pthread_mutexattr_gettype_np Obtains the mutex type attribute used when a mutex is created. 4 C_Binding #include <pthread.h> int pthread_mutexattr_gettype_np ( const pthread_mutexattr_t *attr, int *type); 4 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 4 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. 4 Return_Values On successful completion, this routine returns the mutex type in type. 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. 4 Associated_Routines pthread_mutexattr_init() pthread_mutexattr_settype_np() pthread_mutex_init() 3 pthread_mutexattr_init Initializes a mutex attributes object. 4 C_Binding #include <pthread.h> int pthread_mutexattr_init ( pthread_mutexattr_t *attr); 4 Arguments attr Mutex attributes object to be initialized. 4 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. 4 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. [ENOMEM] Insufficient memory while attempting to create the mutex attributes object. 4 Associated_Routines pthread_create() pthread_mutexattr_gettype_np() pthread_mutexattr_settype_np() pthread_mutex_init() 3 pthread_mutexattr_settype_np Specifies the mutex type attribute that is used when a mutex is created. 4 C_Binding #include <pthread.h> int pthread_mutexattr_settype_np ( pthread_mutexattr_t *attr, int type); 4 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 4 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(). 4 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. 4 Associated_Routines pthread_mutexattr_init() pthread_mutexattr_gettype_np() pthread_mutex_init() 3 pthread_once Calls an initialization routine that is executed by a single thread, once. 4 C_Binding #include <pthread.h> int pthread_once ( pthread_once_t *once_control, void (*init_routine) (void)); 4 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(). 4 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); } 4 Return_Values If an error occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] Invalid argument. 3 pthread_self Obtains the identifier of the current thread. 4 C_Binding #include <pthread.h> pthread_t pthread_self (void); 4 Arguments None 4 Description This routine allows a thread to obtain its own thread identifier. This value becomes meaningless after the thread is destroyed. 4 Return_Values Returns the identifier of the calling thread. 4 Associated_Routines pthread_cancel() pthread_create() pthread_detach() pthread_exit() pthread_join() pthread_kill() pthread_sigmask() 3 pthread_setcancelstate Sets the calling thread's cancelability state. 4 C_Binding #include <pthread.h> int pthread_setcancelstate ( int state, int *oldstate ); 4 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. 4 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. 4 Return_Values On successful completion, this routine returns the calling thread's previous cancelability state in oldstate. 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. 4 Associated_Routines pthread_cancel() pthread_setcanceltype() pthread_testcancel() 3 pthread_setcanceltype Sets the calling thread's cancelability type. 4 C_Binding #include <pthread.h> int pthread_setcanceltype ( int type, int *oldtype); 4 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. 4 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: o 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 cancellation point (including condition waits, thread joins, and calls to pthread_testcancel()). o 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. 4 Return_Values On successful completion, this routine returns the previous cancelability type in oldtype. 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. 4 Associated_Routines pthread_cancel() pthread_setcancelstate() pthread_testcancel() 3 pthread_setschedparam Changes a thread's scheduling policy and scheduling parameters. 4 C_Binding #include <pthread.h> int pthread_setschedparam ( pthread_t thread, int policy, const struct sched_param *param); 4 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 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. 4 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. 4 Return_Values If an error condition occurs, no scheduling policy or parameters are changed for the target thread, and 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 policy or param is invalid. [ENOTSUP] An attempt is made to set the scheduling policy or a parameter to an unsupported value. [EPERM] The caller does not have the appropriate privileges to set the scheduling policy or parameters of the specified thread. [ESRCH] The value specified by thread does not refer to an existing thread. 4 Associated_Routines pthread_attr_getschedparam() pthread_attr_setschedpolicy() pthread_create() pthread_self() sched_yield() 3 pthread_setspecific Sets the thread-specific data value associated with the specified key for the calling thread. 4 C_Binding #include <pthread.h> int pthread_setspecific ( pthread_key_t key, const void *value); 4 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. 4 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. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The specified key is invalid. [ENOMEM] Insufficient memory exists to associate the value with the key. 4 Associated_Routines pthread_getspecific() pthread_key_create() pthread_key_delete() 3 pthread_testcancel Requests delivery of any pending cancelation request to the calling thread. 4 C_Binding #include <pthread.h> void pthread_testcancel (void); 4 Arguments None 4 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. 4 Return_Values None 4 Associated_Routines pthread_setcancelstate() 3 pthread_unlock_global_np Unlocks the DECthreads global mutex. 4 C_Binding #include <pthread.h> int pthread_unlock_global_np (void); 4 Arguments None 4 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. 4 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. [EPERM] The mutex is unlocked or owned by another thread. 4 Associated_Routines pthread_lock_global_np() 3 sched_yield Yields execution to another thread. 4 C_Binding #include <sched.h> #include <unistd.h> int sched_yield ( void); 4 Arguments None 4 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. 4 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. -1 Unsuccessful completion - errno is set to indicate that an error occurred. [ENOSYS] The function sched_yield() is not supported by this implementation. 4 Associated_Routines pthread_attr_setschedparam() pthread_setschedparam() pthread_getscheduler() 2 TIS_routines The Digital proprietary DECthreads TIS interface provides routines that you use to build thread-safe libraries whose own routines do not create threads, but which can safely be called from a multithreaded environment. TIS routines are functionally identical to their corresponding routines in the DECthreads PTHREAD interface. See the Guide to DECthreads documentation for more information. In a program that creates threads, TIS routines provide full thread synchronization and memory coherence. But, when run in a program that does not use threads, the same TIS calls provide low-overhead "stub" implementations of PTHREAD features. That is, the objects created using the TIS interface are the same as PTHREAD objects. When threads are present, the guidelines for using PTHREAD routines apply also to the use of the corresponding TIS routine. 3 tis_cond_broadcast Wakes all threads that are waiting on a condition variable. 4 C_Binding #include <tis.h> int tis_cond_broadcast ( pthread_cond_t *cond); 4 Arguments cond Address of the condition variable (passed by reference) on which to broadcast. 4 Description When threads are not present, tis_cond_broadcast() performs no actions. When threads are present, tis_cond_broadcast() unblocks all threads waiting on the specified condition variable cond. For further information about actions when threads are present, refer to the pthread_cond_broadcast() description. 4 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 cond is invalid. 4 Associated_Routines tis_cond_destroy() tis_cond_init() tis_cond_signal() tis_cond_wait() 3 tis_cond_destroy Destroys a condition variable. 4 C_Binding #include <tis.h> int tis_cond_destroy ( pthread_cond_t *cond); 4 Arguments cond Address of the condition variable (passed by reference) to be destroyed. 4 Description This routine destroys the condition variable specified by cond. After this routine is called, DECthreads may reclaim internal storage used by the condition variable object. Call this routine when a condition variable will no longer be referenced. The results of this routine are unpredictable, if the condition variable specified in cond does not exist or is not initialized. For more information about actions when threads are present, refer to the pthread_cond_destroy() description. 4 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 cond is invalid. [EBUSY] The object being referenced by cond is being referenced by another thread that is currently executing a tis_cond_wait() on the condition variable specified in cond. (This error can only occur when threads are present.) 4 Associated_Routines tis_cond_broadcast() tis_cond_init() tis_cond_signal() tis_cond_wait() 3 tis_cond_init Initializes a condition variable. 4 C_Binding #include <tis.h> int tis_cond_init ( pthread_cond_t *cond); 4 Arguments cond Address of the condition variable (passed by reference) to be initialized. 4 Description This routine initializes a condition variable (cond) with the DECthreads default condition variable attributes. A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to shared data. When threads are present, a condition variable allows threads to wait for data to enter a defined state. For further information about actions when threads are present, refer to the pthread_cond_init() description. Your program can use the macro PTHREAD_COND_INITIALIZER to initialize statically allocated condition variables to the default condition variable attributes. Use this macro as follows: pthread_cond_t condition = PTHREAD_COND_INITIALIZER; When statically initialized, a condition variable should not also be initialized using tis_cond_init(). Also, a statically initialized condition variable need not be destroyed using tis_ cond_destroy(). 4 Return_Values If there is an error condition, the following occurs: o The routine returns an integer value indicating the type of error. o The condition variable is not initialized. o The contents of conditon variable (cond) are undefined. The possible return values are as follows: Return Description 0 Successful completion. [EAGAIN] The system lacks the necessary resources to initialize another condition variable, or: The system-imposed limit on the total number of condition variables under execution by a single user is exceeded. [EBUSY] The implementation has detected an attempt to reinitialize the object referenced by cond, a previously initialized, but not yet destroyed condition variable. [EINVAL] The value specified by attr is invalid. [ENOMEM] Insufficient memory exists to initialize the condition variable. 4 Associated_Routines tis_cond_broadcast() tis_cond_destroy() tis_cond_signal() tis_cond_wait() 3 tis_cond_signal Wakes at least one thread that is waiting on a condition variable. 4 C_Binding #include <tis.h> int tis_cond_signal ( pthread_cond_t *cond); 4 Arguments cond Address of the condition variable (passed by reference) on which to signal. 4 Description When threads are present, this routine unblocks at least one thread waiting on the specified condition variable cond. For more information about actions when threads are present, refer to the pthread_cond_signal() description. 4 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 cond is invalid. 4 Associated_Routines tis_cond_broadcast() tis_cond_destroy() tis_cond_init() tis_cond_wait() 3 tis_cond_wait Causes a thread to wait for a condition variable to be signaled or broadcasted. 4 C_Binding #include <tis.h> int tis_cond_wait ( pthread_cond_t *cond, pthread_mutex_t *mutex); 4 Arguments cond Address of the condition variable (passed by reference) on which to wait. mutex Address of the mutex (passed by reference) which is associated with the condition variable specified in cond. 4 Description When threads are present, this routine causes a thread to wait for a condition variable to be signaled or broadcasted. Calling this routine in a nonthreaded environment is a coding error. Because no thread can execute in parallel to issue a tis_ cond_signal() or tis_cond_broadcast(), using this routine in a single-threaded environment forces the program to exit. For further information about actions when threads are present, refer to the pthread_cond_wait() description. 4 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 cond or mutex is invalid, or: Different mutexes are supplied for concurrent tis_cond_wait() operations on the same condition variable, or: The mutex was not owned by the current thread at the time of the call. 4 Associated_Routines tis_cond_broadcast() tis_cond_destroy() tis_cond_init() tis_cond_signal() 3 tis_getspecific Obtains the data associated with the specified key. 4 C_Binding #include <tis.h> void * tis_getspecific ( pthread_key_t key); 4 Arguments key key identifies a value returned by a call to tis_key_create(). This routine returns the data value associated with the key. 4 Description This routine returns the value currently bound to the specified key. This routine may be called from a data destructor function. When threads are present, the data and keys are thread-specific; they enable a library to maintain context on a per-thread basis. 4 Return_Values No errors are returned. This routine returns the data value associated with the given key. If no data value is associated with key, or if key is not defined, then a NULL value is returned. 4 Associated_Routines tis_key_create() tis_key_delete() tis_setspecific() 3 tis_key_create Generates a unique thread-specific data key. 4 C_Binding #include <tis.h> int tis_key_create ( pthread_key_t *key, void (*destructor)(void *)); 4 Arguments key Address of a variable that will receive the key value. This value is used in calls to tis_getspecific() and tis_setspecific() to get and set the value associated with this key. destructor Address of a routine that is called to destroy the context value when a thread terminates with a non-NULL value for the key. Note that this argument is only used when threads are present. 4 Description This routine generates a unique thread-specific data key. The variable key provided by this routine is an opaque object used to locate data. This routine generates and returns a new key value. The key reserves a cell. Each call to this routine creates a new cell that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the tis_once() description for more information.) An optional destructor function may be associated with each key. At thread exit, if a key has a non-NULL destructor function pointer, and the thread has a non-NULL value associated with that key, the function pointed to is called with the current associated value as its sole argument. The order in which data destructors are called at thread termination is undefined. When threads are present, keys and any corresponding data are thread-specific; they enable the context to be maintained on a per-thread basis. For more information concerning the use of tis_ key_create() in a threaded environment, refer to the pthread_key_ create() description. DECthreads imposes a maximum number of thread-specific data keys, equal to the symbolic constant PTHREAD_KEYS_MAX. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EAGAIN] The system lacked the necessary resources to create another thread-specific data key, or the DECthreads- imposed limit on the total number of keys per process (PTHREAD_KEYS_MAX) has been exceeded. [ENOMEM] Insufficient memory exists to create the key. [EINVAL] Invalid argument. 4 Associated_Routines tis_getspecific() tis_key_delete() tis_setspecific() tis_once() 3 tis_key_delete Deletes a thread-specific data key. 4 C_Binding #include <tis.h> int tis_key_delete ( pthread_key_t key); 4 Arguments key Context key to be deleted. 4 Description This routine deletes a thread-specific data key key previously returned by tis_key_create(). The 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 data. This cleanup can be done before or after this routine call. Attempting to use the thread-specific data key key after calling this routine 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. This routine can be called from destructor functions. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The key value is invalid. 4 Associated_Routines tis_getspecific() tis_key_create() tis_setspecific() 3 tis_lock_global Locks the DECthreads global mutex. 4 C_Binding #include <tis.h> int tis_lock_global (void); 4 Arguments None 4 Description This routine locks the DECthreads global mutex. The global mutex is recursive. For example, if you called tis_lock_global() three times, tis_unlock_global() unlocks the global mutex when you call it the third time. For more information about actions when threads are present, refer to the pthread_lock_global_np() description. 4 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. 4 Associated_Routines tis_unlock_global() 3 tis_mutex_destroy Destroys a mutex. 4 C_Binding #include <tis.h> int tis_mutex_destroy ( pthread_mutex_t *mutex); 4 Arguments mutex Address of the mutex (passed by reference) to be destroyed. 4 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. 4 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. [EPERM] The caller does not have privileges to perform the operation. 4 Associated_Routines tis_mutex_init() tis_mutex_lock() tis_mutex_trylock() tis_mutex_unlock() 3 tis_mutex_init Initializes a mutex. 4 C_Binding #include <tis.h> int tis_mutex_init ( pthread_mutex_t *mutex ); 4 Arguments mutex Pointer to a mutex (passed by reference) that is initialized. 4 Description This routine initializes a mutex with the DECthreads default mutex attributes. 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. Mutexes can be allocated in heap or static memory, but not on a stack. The PTHREAD_MUTEX_INITIALIZER macro can be used to statically initialize a mutex without calling this routine. Statically initialized mutexes need not be destroyed using tis_mutex_ destroy(). Use this macro as follows: pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; 4 Return_Values If an error condition occurs, this routine returns an integer value indicating the type of error, the mutex is not initialized, and the contents of mutex are undefined. Possible return values are as follows: Return Description 0 Successful completion. [EAGAIN] The system lacks the necessary resources to initialize a mutex. [ENOMEM] Insufficient memory exists to initialize the mutex. [EBUSY] The implementation has detected an attempt to reinitialize the mutex (a previously initialized, but not yet destroyed mutex). [EINVAL] The value specified by mutex is invalid. [EPERM] The caller does not have privileges to perform this operation. 4 Associated_Routines tis_mutex_lock() tis_mutex_trylock() tis_mutex_unlock() tis_mutex_destroy() 3 tis_mutex_lock Locks an unlocked mutex. 4 C_Binding #include <tis.h> int tis_mutex_lock ( pthread_mutex_t *mutex); 4 Arguments mutex Address of the mutex (passed by reference) to be locked. 4 Description This routine locks a mutex. A deadlock can result if the owner of a mutex calls this routine in an attempt to lock the mutex a second time. (The deadlock is not detected or reported.) In a threaded environment, 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 current thread as the mutex's current owner. 4 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 mutex is invalid. [EDEADLK] A deadlock condition is detected. 4 Associated_Routines tis_mutex_destroy() tis_mutex_init() tis_mutex_trylock() tis_mutex_unlock() 3 tis_mutex_trylock Attempts to lock a mutex. 4 C_Binding #include <tis.h> int tis_mutex_trylock ( pthread_mutex_t *mutex); 4 Arguments mutex Address of the mutex (passed by reference) to be locked. 4 Description This routine attempts to lock a mutex. When this routine is called, an attempt is made to immediately lock the mutex. If the mutex is successfully locked, zero (0) is returned. If the specified mutex is locked when this routine is called, the caller does not wait for the mutex to become available. [EBUSY] is returned, and the thread does not wait to acquire the lock. 4 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] The mutex is already locked; therefore, it was not acquired. [EINVAL] The value specified by mutex is invalid. 4 Associated_Routines tis_mutex_destroy() tis_mutex_init() tis_mutex_lock() tis_mutex_unlock() 3 tis_mutex_unlock Unlocks a mutex. 4 C_Binding #include <tis.h> int tis_mutex_unlock ( pthread_mutex_t *mutex); 4 Arguments mutex Address of the mutex (passed by reference) which is to be unlocked. 4 Description This routine unlocks a mutex. For more information about actions when threads are present, refer to the pthread_mutex_unlock() description. 4 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 mutex is invalid. [EPERM] The caller does not own the mutex. 4 Associated_Routines tis_mutex_destroy() tis_mutex_init() tis_mutex_lock() tis_mutex_trylock() 3 tis_once Calls a one-time initialization routine that can be executed by only one thread, once. 4 C_Binding #include <tis.h> int tis_once ( pthread_once_t *once_control, void (*init_routine) (void)); 4 Arguments once_control Address of a record (control block) that defines the one-time initialization code. Each one-time initialization routine in static storage 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 tis_once(). 4 Description The first call to this routine by a process with a given once_ control will call the init_routine with no arguments. Then subsequent calls to tis_once() with the same once_control will not call the init_routine. On return from tis_once(), it is guaranteed that the initialization routine has completed. For example, a mutex or a thread-specific data key must be created exactly once. In a threaded environment, calling tis_ once() ensures that the initialization is serialized across multiple threads. The once_control variable must be statically initialized using the PTHREAD_ONCE_INIT macro or by zeroing out the entire structure. NOTE If you specify an init_routine that directly or indirectly results in a recursive call to tis_once() and that specifies the same init_block argument, the recursive call will result in a deadlock. The PTHREAD_ONCE_INIT macro, defined in the tis.h header file, must be used to initialize a once_control record. Thus, your program must declare a 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 tis_once(). For example, you can code an "init" routine that begins tith the following basic logic: init() { static pthread_mutex_t mutex = PTHREAD_MUTEX_INIT; static int flag = FALSE; tis_mutex_lock(&mutex); if(!flag) { flag = TRUE; /* initialize code */ } tis_mutex_unlock(&mutex); } 4 Return_Values If an error occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] Invalid argument. 3 tis_read_lock Acquires a readers/writer lock in read access mode. 4 C_Binding #include <tis.h> int tis_read_lock ( tis_rwlock_t *lock); 4 Arguments lock Address of the readers/writer lock. 4 Description This routine acquires a readers/writer lock in read access mode. This routine waits for any existing write access mode lock holder to relinquish its lock before granting the lock in read access mode. It returns when the lock is acquired. If the lock is already held in read access mode, the lock is granted. For each call to tis_read_lock() that successfully acquires the lock in read access mode, a corresponding call tis_read_unlock() must be issued. Note that the type tis_rwlock_p is a pointer to type tis_rwlock_ t. 4 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 lock is invalid. 4 Associated_Routines tis_read_trylock() tis_read_unlock() tis_rwlock_destroy() tis_rwlock_init() tis_write_lock() tis_write_trylock() tis_write_unlock() 3 tis_read_trylock Attempts to acquire a readers/writer lock in read access mode. Does not wait if the lock cannot be immediately granted. 4 C_Binding #include <tis.h> int tis_read_trylock ( tis_rwlock_t *lock); 4 Arguments lock Address of the readers/writer lock. 4 Description This routine attempts to acquire a readers/writer lock in read access mode. If the lock cannot be granted, the routine returns without waiting. When a thread calls this routine, an attempt is made to immediately acquire the lock in read mode. If the lock is acquired, zero (0) is returned. If a write access mode lock holder exists, [EBUSY] is returned. If the lock cannot be obtained immediately, the calling program does not wait for the lock to be released. 4 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; the lock was acquired. [EBUSY] The lock is being held with write access mode. The lock was not acquired. 4 Associated_Routines tis_read_lock() tis_read_unlock() tis_rwlock_destroy() tis_rwlock_init() tis_write_lock() tis_write_trylock() tis_write_unlock() 3 tis_read_unlock Unlocks a readers/writer lock that was acquired in read access mode. 4 C_Binding #include <tis.h> int tis_read_unlock ( tis_rwlock_t *lock); 4 Arguments lock Address of the readers/writer lock. 4 Description This routine unlocks a readers/writer lock that was acquired in read access mode. If there are no other holders of the lock with read access mode and another thread is waiting to acquire the lock in write access mode, the lock will now be granted. 4 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 lock is invalid. 4 Associated_Routines tis_read_lock() tis_read_trylock() tis_rwlock_destroy() tis_rwlock_init() tis_write_lock() tis_write_trylock() tis_write_unlock() 3 tis_rwlock_destroy Destroys a readers/writer lock. 4 C_Binding #include <tis.h> int tis_rwlock_destroy ( tis_rwlock_t *lock); 4 Arguments lock Address of the readers/writer lock structure to be destroyed. 4 Description This routine destroys a readers/writer lock. The routine has the reverse operation of the tis_rwlock_init() routine, which began the session by initializing the tis_rwlock_t structure. Ensure that there are no locks granted, or threads waiting for locks to be granted, prior to calling this routine. This routine should be called only after the readers and writer are done using the lock. 4 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] The lock is in use. 4 Associated_Routines tis_read_lock() tis_read_trylock() tis_read_unlock() tis_rwlock_init() tis_write_lock() tis_write_trylock() tis_write_unlock() 3 tis_rwlock_init Initializes a readers/writer lock. 4 C_Binding #include <tis.h> int tis_rwlock_init ( tis_rwlock_t *lock); 4 Arguments lock Address of a readers/writer lock structure. 4 Description This routine initializes a readers/writer lock. The routine initializes the tis_rwlock_t structure that holds the lock states. To destroy a readers/writer lock, call the tis_rwlock_destroy() routine. 4 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 lock is invalid. [ENOMEM] Insufficient memory exists to establish lock. 4 Associated_Routines tis_read_lock() tis_read_trylock() tis_read_unlock() tis_rwlock_destroy() tis_write_lock() tis_write_trylock() tis_write_unlock() 3 tis_self Obtains the identifier of the current thread. 4 C_Binding #include <tis.h> pthread_t tis_self (void); 4 Arguments None 4 Description This routine allows a thread to obtain its own thread identifier. This value becomes meaningless when the thread is deleted. The initial thread in a process may "change identity" when thread system initialization completes-that is, when the DECthreads library is loaded. 4 Return_Values Returns the thread identifier of the caller. 4 Associated_Routines pthread_create() 3 tis_setcancelstate Sets the caller's cancelability state. 4 C_Binding #include <tis.h> int tis_setcancelstate ( int state, int *oldstate ); 4 Arguments state State of general cancelability to set for the calling thread. Valid state values are as follows: PTHREAD_CANCEL_ENABLE PTHREAD_CANCEL_DISABLE oldstate Previous cancelability state. 4 Description This routine sets the caller's cancelability state to the value specified in the state argument and returns the previous cancelability state to the location referenced by the oldstate argument. 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 is enabled. When a thread is created, its default cancelability state is PTHREAD_CANCEL_ENABLE. When this routine is called prior to loading threads, the cancel state propagates to the initial thread in the executing program. Possible Problems When Disabling Cancelability The most important use of a cancelation request is to ensure that indefinite wait operations are terminated. For example, a thread waiting on some network connection, which may take days to respond (or may never respond), should be made cancelable. When cancelability state is disabled, no routine is cancelable. As a result, the user is unable to cancel the operation. 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. 4 Return_Values On successful completion, this routine returns the caller's previous cancelability state in the oldstate argument. 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. 4 Associated_Routines tis_testcancel() 3 tis_setspecific Sets the value associated with the specified thread-specific data key. 4 C_Binding #include <tis.h> int tis_setspecific ( pthread_key_t key, const void *value); 4 Arguments key Thread-specific data key that identifies the data to receive value. Must be obtained from tis_key_create(). value New value to associate with the specified key. Once set, this value can be retrieved using the same key in a call to tis_ getspecific(). 4 Description This routine sets the value associated with the specified thread- specific data key. If a value is defined for the key (that is, the current value is not NULL), the new value is substituted for it. The key is obtained by a previous call to tis_key_create(). Do not call this routine from a data destructor function. 4 Return_Values If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The key value is invalid. [ENOMEM] Insufficient memory exists to associate the value with the key. 4 Associated_Routines tis_getspecific() tis_key_create() tis_key_delete() 3 tis_testcancel Creates a cancelation point in the calling thread. 4 C_Binding #include <tis.h> void tis_testcancel (void); 4 Arguments None 4 Description This routine requests delivery of a pending cancelation request to the calling thread. Thus, this routine creates a cancellation point in 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 tis_setcancelstate().) This routine, when called within very long loops, ensures that a pending cancelation request is noticed within a reasonable amount of time. 4 Return_Values None 4 Associated_Routines tis_setcancelstate() 3 tis_unlock_global Unlocks the DECthreads global mutex. 4 C_Binding #include <tis.h> int tis_unlock_global (void); 4 Arguments None 4 Description This routine unlocks the DECthreads global mutex. Because the global mutex is recursive, the unlock will occur when each call to tis_lock_global() has been matched by a call to this routine. For example, if you called tis_lock_global() three times, tis_ unlock_global() unlocks the global mutex when you call it the third time. For more information about actions when threads are present, refer to the pthread_unlock_global_np() description. 4 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. [EPERM] The global mutex is unlocked or locked by another thread. 4 Associated_Routines tis_lock_global() 3 tis_write_lock Acquires a readers/writer lock in write access mode. 4 C_Binding #include <tis.h> int tis_rwlock ( tis_rwlock_t *lock); 4 Arguments lock Address of the readers/writer lock. 4 Description This routine acquires a readers/writer lock in write access mode. This routine waits for any other active locks (in either read access or write access mode) to become unlocked before the lock request is granted. The routine returns when the readers/writer lock is established. 4 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 lock is invalid. 4 Associated_Routines tis_read_lock() tis_read_trylock() tis_read_unlock() tis_rwlock_destroy() tis_rwlock_init() tis_write_trylock() tis_write_unlock() 3 tis_write_trylock Attempts to acquire a readers/writer lock in write access mode. 4 C_Binding #include <tis.h> int tis_write_trylock ( tis_rwlock_t *lock); 4 Arguments lock Address of the readers/writer lock. 4 Description This routine attempts to acquire a readers/writer lock in write access mode. An attempt is made to immediately acquire the lock. If the lock is acquired, zero (0) is returned. If the lock is held by another thread (in either read access mode or write access mode), [EBUSY] is returned and the caller does not wait for an eventual lock. Note that it is a coding error to attempt to acquire the lock in write access mode if the lock is already held by the calling thread. (However, this routine returns [EBUSY] anyway, because no ownership error-checking takes place.) 4 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; the write lock is acquired. [EBUSY] The lock in write access mode was not acquired, as it is already held by another thread. 4 Associated_Routines tis_read_lock() tis_read_trylock() tis_read_unlock() tis_rwlock_destroy() tis_rwlock_init() tis_write_lock() tis_write_unlock() 3 tis_write_unlock Unlocks a readers/writer lock. 4 C_Binding #include <tis.h> int tis_write_unlock ( tis_rwlock_t *lock); 4 Arguments lock Address of the readers/writer lock. 4 Description This routine unlocks a readers/writer lock that was acquired in write access mode. Upon completion of this routine, any thread waiting to acquire the lock in read access mode will have the locks granted. If no threads are waiting to acquire the lock in read access mode, then a thread waiting to acquire it in write access mode will have the lock granted. 4 Return_Values If an error condition occurs, this routine returns an integer value indicating the type error. Possible return values are as follows: Return Description 0 Successful completion. [EINVAL] The value specified by lock is invalid. 4 Associated_Routines tis_read_lock() tis_read_trylock() tis_read_unlock() tis_rwlock_init() tis_rwlock_destroy() tis_write_lock() tis_write_trylock()
Software development, photography, jokes, ....
Hosting Favorites |
| ANU Internet Services |
| Netim |
| GoDaddy |
| XEL Media |
Blogroll |
| Bomenstichting |
| Google Translate |
| PHP |
| MySQL |
| jQuery |
| jQuery UI |
| YourHead Stacks API |
| Favicon Generator. |
| Password Generator. |
| Check HTTPS problems |
Tweets by MrMacvos
Marc's Place
On this website, Google Analytics is used to track visitor statistics. These are anonymised data about the number of visitors, which pages they visit on this site, from which regions they visit, which web browsers they use, etc.. You will also see non-personalised ads via Google AdSense. Cookies from Paddle or Paypal are placed when you click on a 'Buy now!' or 'Donate!' button, and possible cookies from Disqus when you use that system to comment on one or more blogposts.
Privacy Statement