home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / f90 / omp_threads.z / omp_threads
Encoding:
Text File  |  2002-10-03  |  14.5 KB  |  250 lines
  1. omp_threads(3)                  UNICOS 10.0           Last changed: 1-27-99
  2.  
  3.  
  4. NNAAMMEE
  5.      oommpp__sseett__nnuumm__tthhrreeaaddss, oommpp__ggeett__nnuumm__tthhrreeaaddss, oommpp__ggeett__mmaaxx__tthhrreeaaddss,
  6.      oommpp__ggeett__tthhrreeaadd__nnuumm, oommpp__ggeett__nnuumm__pprrooccss, oommpp__sseett__ddyynnaammiicc,
  7.      oommpp__ggeett__ddyynnaammiicc, oommpp__iinn__ppaarraalllleell, OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS,
  8.      OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS, OOMMPP__GGEETT__MMAAXX__TTHHRREEAADDSS, OOMMPP__GGEETT__TTHHRREEAADD__NNUUMM,
  9.      OOMMPP__GGEETT__NNUUMM__PPRROOCCSS, OOMMPP__SSEETT__DDYYNNAAMMIICC, OOMMPP__GGEETT__DDYYNNAAMMIICC, OOMMPP__IINN__PPAARRAALLLLEELL -
  10.      Runtime library procedures used to set, call or return numbers of
  11.      threads
  12.  
  13. SSYYNNOOPPSSIISS
  14.      C/C++:
  15.           ##iinncclluuddee <<oommpp__sseett__nnuumm__tthhrreeaaddss>>
  16.           vvooiidd oommpp__sseett__nnuumm__tthhrreeaaddss ((_i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n))
  17.  
  18.           ##iinncclluuddee <<oommpp__ggeett__nnuumm__tthhrreeaaddss>>
  19.           iinntt oommpp__ggeett__nnuumm__tthhrreeaaddss(())
  20.  
  21.           ##iinncclluuddee <<oommpp__ggeett__mmaaxx__tthhrreeaaddss>>
  22.           iinntt oommpp__ggeett__mmaaxx__tthhrreeaaddss(())
  23.  
  24.           ##iinncclluuddee <<oommpp__ggeett__tthhrreeaadd__nnuumm>>
  25.           iinntt oommpp__ggeett__tthhrreeaadd__nnuumm(())
  26.  
  27.           ##iinncclluuddee <<oommpp__ggeett__nnuumm__pprrooccss>>
  28.           iinntt oommpp__ggeett__nnuumm__pprrooccss(())
  29.  
  30.           ##iinntteeggeerr <<oommpp__sseett__ddyynnaammiicc>>
  31.           vvooiidd oommpp__sseett__ddyynnaammiicc((_i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n))
  32.  
  33.           ##iinntteeggeerr <<oommpp__ggeett__ddyynnaammiicc>>
  34.           iinntt oommpp__ggeett__ddyynnaammiicc(())
  35.  
  36.           ##iinntteeggeerr <<oommpp__iinn__ppaarraalllleell>>
  37.           vvooiidd oommpp__iinn__ppaarraalllleell(())
  38.  
  39.      Fortran:
  40.           CCAALLLL OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS ((_i_n_t_e_g_e_r-_e_p_x_r_e_s_s_i_o_n))
  41.  
  42.           IINNTTEEGGEERR OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS(())
  43.  
  44.           IINNTTEEGGEERR OOMMPP__GGEETT__MMAAXX__TTHHRREEAADDSS(())
  45.  
  46.           IINNTTEEGGEERR OOMMPP__GGEETT__TTHHRREEAADD__NNUUMM(())
  47.  
  48.           IINNTTEEGGEERR OOMMPP__GGEETT__NNUUMM__PPRROOCCSS(())
  49.  
  50.           CCAALLLL OOMMPP__SSEETT__DDYYNNAAMMIICC((_l_o_g_i_c_a_l-_e_x_p_r_e_s_s_i_o_n))
  51.  
  52.           LLOOGGIICCAALL OOMMPP__GGEETT__DDYYNNAAMMIICC(())
  53.  
  54.           LLOOGGIICCAALL OOMMPP__IINN__PPAARRAALLLLEELL(())
  55.  
  56. IIMMPPLLEEMMEENNTTAATTIIOONN
  57.      UNICOS and IRIX systems
  58.  
  59. SSTTAANNDDAARRDDSS
  60.      OpenMP Fortran API
  61.      OpenMP C/C++ API
  62.  
  63. DDEESSCCRRIIPPTTIIOONN
  64.      The following descriptions contain information for Fortran and C/C++.
  65.  
  66.      oommpp__sseett__nnuumm__tthhrreeaaddss, OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS
  67.           This procedure sets the number of threads to use in a team.
  68.  
  69.      The _i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n is evaluated, and its value is used as the
  70.      number of threads to use beginning with the next non-nested parallel
  71.      region.
  72.  
  73.      This call takes precedence over the OOMMPP__NNUUMM__TTHHRREEAADDSS environment
  74.      varable.  When dynamic threads is enabled, this value is interpreted
  75.      to be the maximum number of threads to use.
  76.  
  77.      oommpp__ggeett__nnuumm__tthhrreeaaddss, OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS
  78.           This function returns the number of threads currently in the team
  79.           executing the parallel region from which it is called.
  80.           Mechanisms that control the number of threads include the runtime
  81.           system when dynamic adjustment of the number of threads is
  82.           enabled, the oommpp__sseett__nnuumm__tthhrreeaaddss(()) call (OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS
  83.           call), and the OOMMPP__NNUUMM__TTHHRREEAADDSS environment variable.  The default
  84.           number of threads is implementation dependent in the case that
  85.           the number of threads has not been specified by the user.
  86.  
  87.           This function binds to the closest enclosing ppaarraalllleell (PPAARRAALLLLEELL)
  88.           directive.  When called from a nested parallel region that is
  89.           serialized, this function returns 1.
  90.  
  91.      oommpp__ggeett__mmaaxx__tthhrreeaaddss, OOMMPP__GGEETT__MMAAXX__TTHHRREEAADDSS
  92.           This function returns the maximum value that calls to
  93.           oommpp__ggeett__nnuumm__tthhrreeaaddss (OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS) may return.  If
  94.           oommpp__sseett__nnuumm__tthhrreeaaddss (OOMMPP__SSEETT__NNUUMM__TTHHRREEAADDSS) is called with a larger
  95.           value, subsequent calls o this function will return the larger
  96.           value.  This function may be used to allocate maximal sized per-
  97.           thread data structures when oommpp__sseett__ddyynnaammiicc (OOMMPP__SSEETT__DDYYNNAAMMIICC) is
  98.           set to nnoonn--zzeerroo (TTRRUUEE).  This function has global scope and
  99.           returns the maximum value whether executing from a serial region
  100.           or a parallel region.
  101.  
  102.      oommpp__ggeett__tthhrreeaadd__nnuumm, OOMMPP__GGEETT__TTHHRREEAADD__NNUUMM
  103.           This function returns the thread number within the team.  The
  104.           master thread of the team is thread 0.  The thread number is
  105.           between 0 and oommpp__ggeett__nnuumm__tthhrreeaaddss(())-1 (OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS(())-1)
  106.           inclusive.  This function binds to the closest enclosing ppaarraalllleell
  107.           (PPAARRAALLLLEELL) directive.  If called from a serial region, it returns
  108.           0.  If called from within a nested parallel region that is
  109.           serialized, this function returns 0.
  110.  
  111.      oommpp__ggeett__nnuumm__pprrooccss, OOMMPP__GGEETT__NNUUMM__PPRROOCCSS
  112.           This function returns the number of processors that are available
  113.           to the program.
  114.  
  115.      oommpp__sseett__ddyynnaammiicc, OOMMPP__SSEETT__DDYYNNAAMMIICC
  116.           This function enables or disables dynamic adjustment of the
  117.           number of threads available for execution of parallel regions.
  118.  
  119.           If _i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n (_l_o_g_i_c_a_l-_e_x_p_r_e_s_s_i_o_n) _e_v_a_l_u_a_t_e_s _t_o nnoonn--zzeerroo
  120.           (TTRRUUEE), the number of threads that are used for executing
  121.           subsequent parallel regions may be adjusted automatically by the
  122.           runtime environment to best utilize system resources.  As a
  123.           consequece, the number of threads specified by the user may
  124.           actually be interpreted as a maximum thread count.  The number of
  125.           threads always remains fixed over the duration of each parallel
  126.           region and is reported by oommpp__ggeett__nnuumm__tthhrreeaaddss(())
  127.           (OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS).  If _i_n_t_e_g_e_r-_e_x_p_r_e_s_s_i_o_n (_l_o_g_i_c_a_l-
  128.           _e_x_p_r_e_s_s_i_o_n) evaluates to zzeerroo (FFAALLSSEE), dynamic adjustment is
  129.           disabled.
  130.  
  131.           A call to oommpp__sseett__ddyynnaammiicc (OOMMPP__SSEETT__DDYYNNAAMMIICC) has precedence over
  132.           the OOMMPP__DDYYNNAAMMIICC environment variable.  The default for the
  133.           dynamic adjustment of threads is implementation dependent.  As a
  134.           result, user codes that depend on a specific number of threads
  135.           for correct execution should explicitly disable dynamic threads.
  136.           Implementations are not required to provide the ability to
  137.           dynamically adjust the number of threads, but they are required
  138.           to provide the interface to support portability across all
  139.           platforms.
  140.  
  141.      oommpp__ggeett__ddyynnaammiicc, OOMMPP__GGEETT__DDYYNNAAMMIICC
  142.           This function returns nnoonn--zzeerroo (TTRRUUEE) if dynamic adjustment of
  143.           the number of threads is enabled; otherwise, it returns zzeerroo
  144.           (FFAALLSSEE).
  145.  
  146.      oommpp__iinn__ppaarraalllleell, OOMMPP__IINN__PPAARRAALLLLEELL
  147.           This function returns nnoonn--zzeerroo (TTRRUUEE) if it is within the dynamic
  148.           extent of a parallel region that actually went parallel;
  149.           otherwise, it returns zzeerroo (FFAALLSSEE).  This function can be used to
  150.           determine whether it was called from within a parallel region.
  151.           It has global scope and will return TTRRUUEE from within a nested
  152.           parallel region.
  153.  
  154. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
  155.      OOMMPP__SSCCHHEEDDUULLEE
  156.           This variable applies only to DDOO and PPAARRAALLLLEELL DDOO directives that
  157.           have the schedule type RRUUNNTTIIMMEE.  The schedule type and chunk size
  158.           for all such loops can be set at runtime by setting this
  159.           environment variable to any of the recognized schedule types and
  160.           to an optional chunk size.  For DDOO and PPAARRAALLLLEELL DDOO directives
  161.           that have a schedule type other than RRUUNNTTIIMMEE, this environment
  162.           variable is ignored.  The default value for this environment
  163.           variable is implementation dependent.  If the optional chunk size
  164.           is not set, a chunk size of 1 is assumed, except in the case of a
  165.           SSTTAATTIICC schedule, the chunk size is set to the loop iteration
  166.           space divided by the number of threads applied to the loop.
  167.  
  168.      OOMMPP__NNUUMM__TTHHRREEAADDSS
  169.           This variable sets the number of threads to use during execution,
  170.           unless that number is explicitly changed by calling
  171.           oommpp__sseett__nnuumm__tthhrreeaaddss(()).  When dynamic adjustment of the number of
  172.           threads is enalbed, the value of this environment variable may be
  173.           interpreted as the maximum number of threads to use.  The default
  174.           value is implementation dependent.
  175.  
  176.      OOMMPP__DDYYNNAAMMIICC
  177.           This variable enables or disables dynamic adjustment of the
  178.           number of threads available for execution of parallel regions.
  179.           If set to TTRRUUEE, the number of threads that are used for executing
  180.           parallel regions may be adjusted by the runtime environment to
  181.           best utilize system resources.
  182.  
  183.           If set to FFAALLSSEE, dynamic adjustment is disabled.  The default
  184.           condition is implementation dependent.
  185.  
  186.      OOMMPP__NNEESSTTEEDD
  187.           This variable enables or disables nested parallelism.  If set to
  188.           TTRRUUEE, nested parallelism is enabled; if it is set to FFAALLSSEE, it is
  189.           disabled.  The default value is FFAALLSSEE.
  190.  
  191. EEXXAAMMPPLLEESS
  192.      For the OpenMP directives to be honored by the compiler, you must
  193.      specify --mmpp on your compiler command line explicitly.  In addition,
  194.      --MMPP::ooppeenn__mmpp==OONN, which is the default setting, must be in effect.
  195.  
  196.      Example 1.
  197.  
  198.      Some programs rely on a fixed, prespecified number of threads to
  199.      execute correctly.  Because the default setting for the dynamic
  200.      adjustment of the number of threads is implementation-dependent, such
  201.      programs can choose to turn off the dynamic threads capability and set
  202.      the number of threads explicitly.  This ensures portability.  The
  203.      following Fortran 90 code fragment specifies a fixed number of
  204.      threads:
  205.  
  206.                 CALL OMP_SET_DYNAMIC(.FALSE.)
  207.                 CALL OMP_SET_NUM_THREADS(16)
  208.           !$OMP PARALLEL DEFAULT(PRIVATE)SHARED(X,NPOINTS)
  209.                 IAM = OMP_GET_THREAD_NUM()
  210.                 IPOINTS = NPOINTS/16
  211.                 CALL DO_BY_16(X,IAM,IPOINTS)
  212.           !$OMP END PARALLEL
  213.  
  214.      In the preceding code fragment, the code executes correctly only if it
  215.      is executed by 16 threads.  Note that the number of threads executing
  216.      a parallel region remains constant during a parallel region,
  217.      regardless of the dynamic threads setting.  The dynamic threads
  218.      mechanism determines the number of threads to use at the start of the
  219.      parallel region and keeps it constant for the duration of the region.
  220.  
  221.      Example 2.  Consider the following incorrect Fortran 90 code:
  222.  
  223.                 NP = OMP_GET_NUM_THREADS()
  224.           !$OMP PARALLEL DO SCHEDULE(STATIC)
  225.                 DO I = 0, NP-1
  226.                   CALL WORK(I)
  227.                 ENDDO
  228.           !$OMP END PARALLEL DO
  229.  
  230.      The OOMMPP__GGEETT__NNUUMM__TTHHRREEAADDSS(()) call returns 1 in the serial section of the
  231.      code, so NNPP will always be equal to 1.
  232.  
  233.      To determine the number of threads that will be deployed for the
  234.      parallel region, the call should be inside the parallel region.  The
  235.      following code is a rewrite of the preceding code.  It shows how to
  236.      rewrite the program without including a query for the number of
  237.      threads:
  238.  
  239.           !$OMP PARALLEL PRIVATE(I)
  240.                 I = OMP_GET_THREAD_NUM()
  241.                 CALL WORK(I)
  242.           !$OMP END PARALLEL
  243.  
  244. SSEEEE AALLSSOO
  245.      oommpp__lloocckk(3) for information on how to manipulate locks
  246.  
  247.      oommpp__nneesstteedd(3) to manipulate or report status of nested parallelism
  248.  
  249.      This man page is available only online.
  250.