pthread_scope_options(5)                           pthread_scope_options(5)




 NAME    [Toc]    [Back]
      pthread_scope_options - list of external options to specify the
      scheduling contention scope of threads

 DESCRIPTION    [Toc]    [Back]
      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.

      For HP-UX 11i v2 September 2004 and forward, the default contention
      scope will be PTHREAD_SCOPE_SYSTEM.

      HP-UX 11i v2 September 2004 provides some external options 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    [Toc]    [Back]
           Forces the system scope irrespective of scope specified in the
           attribute for thread creation.

      PTHREAD_FORCE_SCOPE_PROCESS    [Toc]    [Back]
           Forces the process scope irrespective of scope specified in the
           attribute for thread creation.

      PTHREAD_DEFAULT_SCOPE_PROCESS    [Toc]    [Back]
           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.



 Hewlett-Packard Company            - 1 -      HP-UX 11i Version 2: Sep 2004






 pthread_scope_options(5)                           pthread_scope_options(5)




      Note: If an application is compiled with any of the above options on
      11i v2 September 2004, and it has to run on HP-UX 11i v2, it needs to
      be recompiled.  If it is run without recompilation, it will fail with
      "Unresolved symbol" error.

      PTHREAD_COMPAT_MODE compile option that was supported on HP-UX 11i v2
      will continue to be supported on HP-UX 11i v2 September 2004.
      However, if any of the above mentioned new compile options are used,
      PTHREAD_COMPAT_MODE will not have any effect.  If an application is
      compiled with this option on HP-UX 11i v2 September 2004, it will run
      as it is on HP-UX 11i v2 unlike the new compile options.

    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.





 Hewlett-Packard Company            - 2 -      HP-UX 11i Version 2: Sep 2004






 pthread_scope_options(5)                           pthread_scope_options(5)




      Note: The properties file options mxnfromcompatmode and all1x1
      supported on HP-UX 11i v2 will be supported on HP-UX 11i v2 September
      2004 also.  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    [Toc]    [Back]
           Forces the system scope irrespective of scope specified in the
           attribute for thread creation.

      PTHREAD_FORCE_SCOPE_PROCESS    [Toc]    [Back]
           Forces the process scope irrespective of scope specified in the
           attribute for thread creation.

      PTHREAD_DEFAULT_SCOPE_PROCESS    [Toc]    [Back]
           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    [Toc]    [Back]
           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 on HP-UX 11i v2 September
      2004.  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.





 Hewlett-Packard Company            - 3 -      HP-UX 11i Version 2: Sep 2004






 pthread_scope_options(5)                           pthread_scope_options(5)




    EXAMPLES    [Toc]    [Back]
      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 shposix):


         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 shposix):


         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.

 SEE ALSO    [Toc]    [Back]
      pthread(3T), pthread_attr_init(3T), pthread_attr_setscope(3T).


 Hewlett-Packard Company            - 4 -      HP-UX 11i Version 2: Sep 2004