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. The launch policy determines the locality domain where the newly created process or thread will be launched in a ccNUMA system. The locality domains covered by a process's or thread's processor set are the available locality domains.

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.

When a process creates another process (via fork() or vfork()), the child process will inherit the parent process's launch policy. The initial thread in the child process will inherit the launch policy of the creating thread (and not that of its process). Other threads in a multi-threaded process 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.

Refer to mpctl(2) man page for further details on launch policies.

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 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, PTHREAD_POLICY_RR_TREE_NP, PTHREAD_POLICY_FILL_TREE_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 request establishes a round robin launch policy for the specified thread. The successive child threads of the specified thread will be launched on different locality domains in a round robin manner until all available locality domains have been used by threads in the launch tree. At that point, the selection of locality domains begins again from the original locality domain. The answer parameter is ignored.
PTHREAD_POLICY_FILL_NP: This request establishes a fill first launch policy for the specified thread. The successive child threads of the specified thread will be launched on the same locality domain as their parent thread until one thread has been created for each available processor in the domain. At that point, a new locality domain is selected and successive threads are launched there until there is one thread per processor. All available locality domains will be used before the original domain is selected again. The answer parameter is ignored.
PTHREAD_POLICY_PACKED_NP: This request establishes a packed launch policy for the specified thread. The successive child threads are launched on the same locality domain as their parent thread. The answer parameter is ignored.
PTHREAD_POLICY_LEASTLOAD_NP: This request establishes a least loaded launch policy for the specified thread. The successive child threads are launched on the least loaded locality domain in the processor set regardless of the location of their parent thread. The answer parameter is ignored.
PTHREAD_POLICY_RR_TREE_NP: This request establishes a tree based round robin launch policy for the specified thread. This request differs from PTHREAD_POLICY_RR_NP in which threads become part of the launch tree. This launch policy includes all descendents of the target thread in the launch tree. The answer parameter is ignored.
PTHREAD_POLICY_FILL_TREE_NP: This request establishes a tree based fill first launch policy for the specified thread. This request differs from PTHREAD_POLICY_FILL_NP in which threads become part of the launch tree. This launch policy includes all descendents of the target thread in the launch tree. The answer parameter is ignored.
PTHREAD_POLICY_NONE_NP: This request unsets any launch policy in the thread. The system will employ a default, optimal policy in determining where the newly created thread will be launched. The existing binding of the thread is not changed. 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