NAG CL Interface
X06 (Omp)
OpenMP Utilities

This chapter contains utilities for controlling the OpenMP environment for your program. They are based on OpenMP runtime library routines, although their functionality varies slightly.

These functions have been designed to be used with multithreaded implementations of the NAG Library. In these implementations, these functions enable you to change and interrogate the OpenMP threading environment for your whole program. In describing their use we assume you have followed the recommendations in the Users' Note. Functions are provided to control the number of threads, test whether you have active threads, get a thread's unique thread number and enable and disable nested parallelism. Readers are directed to How to Use the NAG Library for a wider discussion on parallelism.

As these functions apply to the whole program they will affect the OpenMP in your calling program, OpenMP used internally in the NAG Library and also multithreading in any underlying vendor libraries, where provided. See the Users' Note of your implementation for information on what underlying libraries have been used and for the scope of the X06 functions.

OpenMP uses the notion of Internal Control Variables (ICVs) to control the behaviour of a multithreaded program. There are only two that are relevant to this chapter. One is used in determining the number of threads and the other controls the nesting of parallel regions. The user does not have direct access to ICVs, but they can be changed or reported with a call to an X06 function.

The function x06xac can be used to determine, at runtime, whether you are using a multithreaded implementation of the NAG Library or not.

If you are not using OpenMP in your program we recommend you set the number of threads with the OMP_NUM_THREADS environment variable as described in the Users' Note. This is the number of threads that will then be used in multithreaded NAG Library functions. The ICV is set from this environment variable but the value can be changed with a call to x06aac. It applies to the next parallel region, whether that is your own, one encountered by a NAG function or an underlying vendor library routine.

Whilst the ICV strongly influences the number of threads used, the design of OpenMP is such that it does not dictate it. Many factors affect the number of threads in a particular parallel region including, but not restricted to, the presence of a num_threads clause and the number of threads already in use by a program. However, in most cases the number of threads requested will be used. The value of the ICV is retrieved with a call to x06acc. The return value is an upper bound on the number of threads. If it is crucial to know the number of threads that are actually in use for a particular parallel region we recommend you get this number with a call to x06abc, once you are inside the parallel region.

OpenMP threads have a unique thread number, which can be retrieved for a particular thread by a call to x06adc. The master thread is always numbered $0$.

To check whether you are in an active parallel region, where there is more than one thread, x06afc can be used.

The functions x06abc, x06adc and x06afc are only relevant when called from within an OpenMP parallel region. This could be one of your own or one in a NAG function. The cases where these routines apply to NAG functions are the ones which take a user-supplied function. There are functions in Chapters D01, D03, E05 and F01 which contain parallel regions that have calls to user-supplied functions from within them. You may, for example, wish to know the thread number, the number of threads or simply check whether this NAG parallel region is an active one in your supplied function.

Nested parallelism is where a parallel region is contained within another. That is, each thread in a region spawns its own inner parallel region of which it is the master thread. x06ajc can be used to enable nested parallelism by setting the number of nested active parallel regions required. x06akc can be used to retrieve this number. You are strongly recommended to set x06ajc to $1$ if you do not require nested parallelism or are unsure whether you do. Note, setting the value to $0$ will disable parallelism altogether.

If you wish to call a NAG multithreaded function and have it execute in parallel from each thread in your own parallel region you will need to set x06ajc to $2$. If you set it to $1$ the NAG function will simply execute in serial. When using nesting the environment variable OMP_NUM_THREADS can be given a comma-separated list of integers representing the number of threads you wish to use at each level of parallelism. Recall that x06aac can be used to set the number of threads for the next parallel region. To change the number of threads for a NAG function in this scenario, you would call x06aac once inside your own parallel region.

When using a serial implementation of the NAG Library the X06 functions return a value in line with your whole program being executed in serial. This is irrespective of what OMP_NUM_THREADS has been set to or if you have compiled your program with OpenMP.

Table 1 shows the behaviour of these functions in serial implementations of the NAG Library.

Note that underlying vendor libraries may still be using multithreading. Check the Users' Note document of your implementation.

If you are using OpenMP in your code together with a serial implementation of the NAG Library, we recommend you use the OpenMP runtime library routines directly to control threading in your program.

None.

The following lists all those functions that have been withdrawn since Mark 24 of the Library or are in the Library, but deprecated.