pthread_scope_options(5)

NAME

pthread_scope_options — list of external options to specify the scheduling contention scope of threads

DESCRIPTION

From HP-UX release 11i version 2 and forward, HP-UX supports the "MxN" thread model. With MxN model, application has the flexibility of selecting the type of thread (determined by the contention scope specified) in the application. Based on the contention scope, there are two types of threads, PTHREAD_SCOPE_SYSTEM threads and PTHREAD_SCOPE_PROCESS threads.

pthread_attr_init() can be used to initialize the attribute object. Subsequently, pthread_attr_setscope() can be used to set the scope explicitly. If pthread_attr_setscope() is not used, the default contention scope is considered.

The default contention scope will be PTHREAD_SCOPE_SYSTEM.

Some external options are provided to control the contention scope without modifying the application source. This is useful for the application developer to check the performance of the application with multiple thread models before deciding on the thread model appropriate for a particular application.

The external scope options can be specified in three different ways:

1.: At compile time.
2.: In Properties file.
3.: Environment variables.

1. Compile Time Options

The options provided at compile time are:

PTHREAD_FORCE_SCOPE_SYSTEM: Forces the system scope irrespective of scope specified in the attribute for thread creation.
PTHREAD_FORCE_SCOPE_PROCESS: Forces the process scope irrespective of scope specified in the attribute for thread creation.
PTHREAD_DEFAULT_SCOPE_PROCESS: If contention scope is set by pthread_attr_setscope(), that scope is considered while creating a thread. Otherwise, PTHREAD_SCOPE_PROCESS is considered.

The compile time option can be specified with -D or by defining the same before including pthread.h in application source files. If none of the above mentioned options is specified, system scope threads will be created unless pthread_attr_setscope(), specifies otherwise.

PTHREAD_COMPAT_MODE compile option is similar to PTHREAD_FORCE_SCOPE_SYSTEM and is provided for backward compatibility. However, if any of the above mentioned new compile options are used, PTHREAD_COMPAT_MODE will not have any effect.

2. Properties File Options

Users are given the flexibility to use a libpthread properties file to specify various tunables for the library, to help in optimizing their applications without making any source code changes. The default path name of the properties file is /usr/lib/libpthread.properties. Note that this file will have to be explicitly created by the user. If the application wants the pthread library to read the tunables from the properties file, the environment variable PTHREAD_TUNE has to be set to 1, on, or ON. The user, through the environment variable PTHREAD_PROPERTY_FILE can specify a different location for the properties file.

In the properties file, lines beginning with # are comments. For non-comment lines, the first and second words are extracted. The first word is expected to be the name of one of the tunables, and the second word is expected to be the value of that variable.

The properties file supports following tunables to control the scope of threads externally:

force_scope_system: Forces the system scope irrespective of scope specified in the attribute for thread creation.
force_scope_process: Forces the process scope irrespective of scope specified in the attribute for thread creation.
default_scope_process: If contention scope is set by pthread_attr_setscope(), that scope is considered while creating a thread. Otherwise, PTHREAD_SCOPE_PROCESS is considered.
default_scope_system: If contention scope is set by pthread_attr_setscope(), that scope is considered while creating a thread. Otherwise, PTHREAD_SCOPE_SYSTEM is considered.

Note: The properties file options mxnfromcompatmode and all1x1 supported on HP-UX 11i v2 will be provided for backward compatibility. However, if any of the above mentioned new properties file options are used, mxnfromcompatmode and all1x1 will not have any effect.

3. Environmental Variables

There are a set of environment variables which when set can override the scope of the threads specified in the application. These environment variables should be set before starting the application to run.

The environmental variables supported for controlling the scope are:

PTHREAD_FORCE_SCOPE_SYSTEM: Forces the system scope irrespective of scope specified in the attribute for thread creation.
PTHREAD_FORCE_SCOPE_PROCESS: Forces the process scope irrespective of scope specified in the attribute for thread creation.
PTHREAD_DEFAULT_SCOPE_PROCESS: If contention scope is set by pthread_attr_setscope(), that scope is considered while creating a thread. Otherwise, PTHREAD_SCOPE_PROCESS is considered.
PTHREAD_DEFAULT_SCOPE_SYSTEM: If contention scope is set by pthread_attr_setscope(), that scope is considered while creating a thread. Otherwise, PTHREAD_SCOPE_SYSTEM is considered.

Note: PTHREAD_COMPAT_MODE environment variable that was supported on HP-UX 11i v2 will continue to be supported and will have the same effect as PTHREAD_FORCE_SCOPE_SYSTEM However, if any of the above mentioned new environment variables are set, PTHREAD_COMPAT_MODE will not have any effect.

Precedence if multiple options are specified:

Environmental variable settings take higher precedence over properties file settings which in turn take higher precedence over compile time options.
If more than one setting is done in one of the ways specified above, force option will take higher precedence over default option and the scope set by pthread_attr_setscope(). System scope takes more precedence than process scope. The contention scope set by pthread_attr_setscope() takes precedence over external scope setting for default scope process and default scope system.

EXAMPLES

1.

The following settings are done in properties file:

force_scope_system 1

default_scope_process 1

export PTHREAD_TUNE=1 and

export PTHREAD_PROPERTY_FILE=user's_properties_file

should be done for the properties file to be read by the pthread library.

If PTHREAD_PROPERTY_FILE is not set, /usr/lib/libpthread.properties will be used.

With these settings, force_scope_system will take the precedence, and system scope will be forced for all thread creations.

2.

If the following options are defined at compile time with -D or defined in one of the application header files: PTHREAD_DEFAULT_SCOPE_SYSTEM and PTHREAD_FORCE_SCOPE_SYSTEM;

PTHREAD_FORCE_SCOPE_SYSTEM will take higher precedence, and system scope threads will be forced even when pthread_attr_setscope() is used to specify the process scope.

3.

If the following environmental variables are set (say, using sh-posix):

export PTHREAD_DEFAULT_SCOPE_PROCESS=1

export PTHREAD_FORCE_SCOPE_SYSTEM=ON

PTHREAD_FORCE_SCOPE_SYSTEM will take higher precedence, and system scope is forced for all the threads created in the process.

4.

If the following environmental variables are set (say, using sh-posix):

export PTHREAD_DEFAULT_SCOPE_SYSTEM=on

export PTHREAD_FORCE_SCOPE_PROCESS=ON

PTHREAD_FORCE_SCOPE_PROCESS will take higher precedence, and process scope is forced for all the threads created in the process.

pthread_scope_options(5)

Technical documentation

» Table of Contents