pthread_resume

NAME

pthread_resume_np(), pthread_continue(), pthread_suspend() — resume execution of a thread, continue execution of a thread, and suspend execution of a thread

SYNOPSIS

#include <pthread.h>

int pthread_continue( 
   pthread_t thread 
); 

int pthread_resume_np( 
   pthread_t thread, 
   int flags 
); 

int pthread_suspend( 
   pthread_t thread 
); 

PARAMETERS

thread

whose execution is to be suspended or resumed.

flags

Flags to be used by pthread_resume_np(). The valid values are:

PTHREAD_COUNT_RESUME_NP: The target thread's suspension count is decremented by one. If the target thread was suspended and has a suspend count greater than one, the thread will not resume execution.
PTHREAD_FORCE_RESUME_NP: The target thread's suspension count is set to zero. The target will resume execution even if its suspend count was greater than one.

DESCRIPTION

The pthread_suspend() function suspends execution of the target thread specified by thread. The target thread may not be suspended immediately (at that exact instant). On successful return from the pthread_suspend() function, thread is no longer executing. Once a thread has been suspended, subsequent calls to the pthread_suspend() function increment a per thread suspension count and return immediately.

Calling pthread_suspend() with the calling thread specified in thread is allowed. Note that in this case the calling thread shall be suspended during execution of the pthread_suspend() function call and shall only return after another thread has called the pthread_resume_np() or pthread_continue() function for thread.

The pthread_continue() function resumes the execution of the target thread thread. If thread was suspended by multiple calls to pthread_suspend(), only one call to pthread_continue() is required to resume the execution of thread. Calling pthread_continue() for a target thread that is not suspended shall have no effect and return no errors. Calling pthread_continue() is equivalent to calling pthread_resume_np() with the flags parameter specified as PTHREAD_FORCE_RESUME_NP.

The pthread_resume_np() function resumes the execution of the target thread specified by thread. If the flags argument is PTHREAD_COUNT_RESUME_NP, the target thread's suspension count is decremented by one. If the flags argument is PTHREAD_FORCE_RESUME_NP, the target thread's suspension count is set to zero. When the target thread's suspension count reaches zero, the target thread is allowed to continue execution. Calling pthread_resume_np() for a target thread that is not suspended shall have no effect and return no errors.

WARNING

This warning is applicable if any of the following conditions is true for a threaded application:

a.: The PTHREAD_FORCE_SCOPE_SYSTEM or PTHREAD_COMPAT_MODE environment variable is set to either 1 or on.
b.: The application's binary is brought forward from a HP-UX 11i v1 release.

In either of the above conditions, it is strongly recommended to set the environment variable PTHREAD_SUSPEND_SYNC to 1 if the application uses pthread_suspend() which is not POSIX compliant. Failing to do so, can lead to undefined behavior.

RETURN VALUE

If successful, pthread_continue(), pthread_suspend() and pthread_resume_np() return zero. Otherwise, an error number shall be returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_suspend() function returns the corresponding error number.

[ESRCH]: The target thread thread is not in the current process.
[EDEADLK]: The target thread thread is the last running thread in the process. The operation would result in deadlock for the process.

If any of the following occur, the pthread_continue() and pthread_resume_np() functions return the corresponding error number.

[ESRCH]: The target thread thread is not in the current process.
[EINVAL]: The value specified by flags is invalid.

APPLICATION USAGE

This functionality enables a process that is multithreaded to temporarily suspend all activity to a single thread of control. When the process is single threaded, the address space is not changing, and a consistent view of the process can be gathered. One example of its use is for garbage collecting. The garbage collector runs asynchronously within the process and assumes that the process is not changing while it is running.

Suspending a thread may have adverse effects on an application. If a thread is suspended while it holds a critical resource, such as a mutex or a read-write lock, the application may stop or even deadlock until the thread is continued. While the thread is suspended, other threads which may contend for the same resource must block until the thread is continued. Depending on application behavior, this may even result in deadlock. Application programmers are advised to either a) only suspend threads which call async-signal safe functions or b) ensure that the suspending thread does not contend for the same resources that the suspended thread may have acquired. Note: this includes resources that may be acquired by libraries.

The pthread_suspend(), pthread_continue(), and pthread_resume_np() functions cannot reliably be used for thread synchronization. Synchronization primitives like mutexes, semaphores, read-write locks, and condition variables should be used instead.

AUTHOR

pthread_suspend() and pthread_continue() were developed by X/Open.

pthread_resume_np() was developed by HP.

STANDARDS CONFORMANCE

pthread_continue(): None.
pthread_resume_np(): None.
pthread_suspend(): None.

pthread_resume_np(3T)

Technical documentation

» Table of Contents

» Index