pthread_launch_policy

NAME

pthread_launch_policy_np() — setting thread launch policies

SYNOPSIS

#include <pthread.h>

int pthread_launch_policy_np( 
   int request, 
   int *answer, 
   pthread_t tid 
); 

PARAMETERS

request: This parameter determines the precise action to be taken by these functions.
answer: This parameter is an output parameter in which values are returned. The meaning of answer depends on request parameter.
tid: This parameter gives the value of the thread id for certain requests.

DESCRIPTION

Each process shall have a launch policy. Each thread shall have a launch policy. The launch policy for a thread does not have to match the launch policy for the process.

When a process creates another process (via fork() or vfork()), the child process will inherit the parent process's launch policy (not the launch policy of the fork'ing thread). The initial thread in the child process shall have a launch policy of MPC_LAUNCH_NONE - no launch policy). Threads other than the initial thread shall inherit their launch policy from the creating thread.

For all launch policies, the target thread is bound to the locality domain on which it was launched. The target is allowed to execute on any processor within that locality domain.

When setting a launch policy, if the target already has processor or locality domain binding, the existing binding will not be overwritten. Instead the locality domain in which the target is bound (whether locality domain binding or processor binding) will be used as the starting locality domain for implementing the launch policy.

Note: locality domains are tightly tied to the physical components of the underlying system. As a result, the performance observed when using launch policies based on locality domains may vary from system to system. For example, a system which contains 4 locality domains, each containing 32 processors, may exhibit different performance behaviors from a system that contains 32 locality domains with 4 processors per domain. The launch policy that provides optimal performance on one system may not provide optimal performance on a different system for the same application.

The pthread_launch_policy_np() function sets a thread launch policy for a specific thread.

The thread specified by tid is the target thread whose launch policy is changed. The value PTHREAD_SELFTID_NP can be used to refer to the calling thread.

The request parameter specifies the action to take and may be one of the following:

PTHREAD_GET_POLICY_NP: The current launch policy of the target thread is returned in the answer parameter. This request currently returns PTHREAD_POLICY_RR_NP, PTHREAD_POLICY_FILL_NP, PTHREAD_POLICY_PACKED_NP, PTHREAD_POLICY_LEASTLOAD_NP, or PTHREAD_POLICY_NONE_NP to indicate the current launch policy of the thread specified by tid. Other launch policies may be added in future releases and returned via this option. Applications using this option should be written to handle other return values in order to continue working on future releases.
PTHREAD_POLICY_RR_NP: This call establishes a round robin policy for the specified thread. Round robin indicates that new threads created by this thread are launched on different locality domains until all domains in the system have been used by the created threads. At that point, the selection of locality domains begins again from the system wide pool of domains. As with all launch policies, the thread is bound to the locality domain on which it was launched. The answer parameter is ignored.
PTHREAD_POLICY_FILL_NP: This call establishes a fill first policy for the specified thread. Fill first indicates that new threads created by this thread are launched on the same locality domain as the creating thread until one thread has been created for each processor in the domain. At that point, a new locality domain is selected and successive threads launched there until there is one thread per processor. All domains in the system will be used before the original domain is selected again. As with all launch policies, the thread is bound to the locality domain on which it was launched. The answer parameter is ignored.
PTHREAD_POLICY_PACKED_NP: This call establishes a packed policy for the specified thread. Packed indicates that new threads created by this thread are launched on the same locality domain as the creating thread. As with all launch policies, the thread is bound to the locality domain on which it was launched. The answer parameter is ignored.
PTHREAD_POLICY_LEASTLOAD_NP: This call establishes a least loaded policy for the specified thread. Least loaded indicates that new threads created by this thread are launched on the least loaded locality domain in the system regardless of the location of the creating thread. As with all launch policies, the thread is bound to the locality domain on which it was launched. The answer parameter is ignored.
PTHREAD_POLICY_NONE_NP: This call unsets any launch policy in the thread. In removing a launch policy, the thread is no longer bound to the locality domain on which it was launched.The answer parameter is ignored.

RETURN VALUE

Upon successful completion, pthread_launch_policy_np() returns zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_launch_policy_np() function returns the corresponding error number:

[EINVAL]: The request parameter contains an illegal value.
[EINVAL]: The value specified by answer is illegal.
[ESRCH]: No thread could be found in the current process that matches the thread ID specified in tid.

WARNINGS

pthread_launch_policy_np() is currently not supported for PTHREAD_SCOPE_PROCESS threads. If pthread_launch_policy_np() is used on a PTHREAD_SCOPE_PROCESS thread, it is silently ignored and zero is returned for successful completion. If the request parameter is PTHREAD_GET_POLICY_NP, answer is set to PTHREAD_POLICY_NONE_NP. For all other request values, answer parameter is ignored. Applications dependent on the complete implementation of pthread_launch_policy_np() should use PTHREAD_SCOPE_SYSTEM threads.

AUTHOR

pthread_launch_policy_np() was developed by HP.

STANDARDS CONFORMANCE

pthread_launch_policy_np(): None.

pthread_launch_policy_np(3T)

Technical documentation

» Table of Contents

» Index