3.2 Parallelizing for OpenMP

The C compiler accepts the OpenMP API for shared memory parallelization natively. The API consists of a set of parallelization pragmas. Information on the OpenMP API specification is at the OpenMP web site athttp://www.openmp.org.

To enable the compiler’s OpenMP support and recognition of the OpenMP pragmas, compile with the -xopenmp option. Without -xopenmp, the compiler treats the OpenMP pragmas as comments. See B.2.131 -xopenmp[=i].

See the Oracle Solaris Studio OpenMP API User’s Guide for details.

3.2.1 Handling OpenMP Runtime Warnings

The OpenMP runtime system can issue warnings for non-fatal errors. Use the following function to register a callback function to handle these warnings:

int sunw_mp_register_warn(void (*func) (void *) )

You can access the prototype for this function by issuing a #include preprocessor directive for <sunw_mp_misc.h>.

If you do not want to register a function, set the environment variable SUNW_MP_WARN to TRUE to send warning messages to stderr.

For information specific to this implementation of OpenMP, including pragmas, environment variables and runtime functions related to OpenMP, see the Oracle Solaris Studio OpenMP API User’s Guide.

3.2.2 Environment Variables

Some environment variables related to parallelized C are the following. There are additional environment variables defined by the OpenMP API specifications and others that are specific to the Oracle Solaris Studio implementation. See the Oracle Solaris Studio OpenMP API User's Guide for descriptions of all parallelization related environment variables.

• PARALLEL or OMP_NUM_THREADS

  Set the PARALLEL environment variable if you can take advantage of multiprocessor execution. The PARALLEL environment variable specifies the number of processors available to the program. The default if not specified is 2.

  If the target machine has multiple processors, the threads can map to independent processors. Running the program leads to the creation of two threads that execute the parallelized portions of the program.

  You can use either PARALLEL or OMP_NUM_THREADS — they are equivalent.

• SUNW_MP_THR_IDLE

  Controls the status of idle threads in an OpenMP program that are waiting at a barrier or waiting for new parallel regions to work on. See the Oracle Solaris Studio OpenMP API User's Guide for details.

• SUNW_MP_WARN

  Set this environment variable to TRUE to print warning messages from OpenMP and other parallelization runtime-systems. See the Oracle Solaris Studio OpenMP API User's Guide for details.

• STACKSIZE

  The executing program maintains a main memory stack for the master thread and distinct stacks for each slave thread. Stacks are temporary memory address spaces used to hold arguments and automatic variables over subprogram invocations.

  The default size of the main stack is about 8 megabytes. Use the limit command to display the current main stack size as well as set it.

  % limit
  cputime unlimited
  filesize unlimited
  datasize 2097148 kbytes
  stacksize 8192 kbytes <- current main stack size
  coredumpsize 0 kbytes
  descriptors 256
  memorysize unlimited
  % limit stacksize 65536 <- set main stack to 64Mb

  Each slave thread of a multithreaded program has its own thread stack. This stack mimics the main stack of the master thread but is unique to the thread. The thread’s private arrays and variables (local to the thread) are allocated on the thread stack.

  All slave threads have the same stack size, which is 4 megabytes for 32-bit applications and 8 megabytes for 64-bit applications by default. The size is set with the STACKSIZE environment variable:

  % setenv STACKSIZE 16483 <- Set thread stack size to 16 Mb

  Setting the thread stack size to a value larger than the default might be necessary for some parallelized code.

  Sometimes the compiler will generate a warning message that indicates a bigger stack size is needed. Determining how large to set it is usually done by trial and error, especially if private/local arrays are involved. If the stack size is too small for a thread to run, the program will quit with a segmentation fault.

  The setting of the STACKSIZE environment variable has no effect on programs using the Oracle Solaris pthreads API.

3.2.3 Using restrict in Parallel Code

The keyword restrict can be used with parallelized C. The proper use of the keyword restrict helps the optimizer in evaluating the aliasing of data required to determine whether a code sequence can be parallelized. Refer to D.1.2 C99 Keywords for details.