OpenMP Pragmas and Options

The omp_set_num_threads function sets the number of threads to use for subsequent parallel regions. The format is as follows:

#include <omp.h>
void omp_set_num_threads(int num_threads);

The value of the parameter num_threads must be positive. Its effect depends upon whether dynamic adjustment of the number of threads is enabled. If dynamic adjustment is disabled, the value is used as the number of threads for all subsequent parallel regions prior to the next call to this function; otherwise, the value is the maximum number of threads that will be used. This function has effect only when called from serial portions of the program. If it is called from a portion of the program where the omp_in_parallel function returns non-zero, the behavior of this function is undefined. For more information on this subject, see the omp_set_dynamic and omp_get_dynamic functions.This call has precedence over the OMP_NUM_THREADS environment variable.

The omp_get_num_threads function returns the number of threads currently in the team executing the parallel region from which it is called. The format is as follows:

#include <omp.h>
int omp_get_num_threads(void);

The omp_set_num_threads function and the OMP_NUM_THREADS environment variable control the number of threads in a team.

If the number of threads has not been explicitly set by the user, the default is implementation dependent. This function binds to the closest enclosing parallel directive. If called from a serial portion of a program, or from a nested parallel region that is serialized, this function returns 1.

The omp_get_max_threads function returns the maximum value that can be returned by calls to omp_get_num_threads. The format is as follows:

#include <omp.h>
int omp_get_max_threads(void);

If omp_set_num_threads is used to change the number of threads, subsequent calls to this function will return the new value. A typical use of this function is to determine the size of an array for which all thread numbers are valid indices, even when omp_set_dynamic is set to non-zero.

This function returns the maximum value whether executing within a serial region or a parallel region.

The omp_get_thread_num function returns the thread number, within its team, of the thread executing the function. The thread number lies between 0 and omp_get_num_threads()-1, inclusive. The master thread of the team is thread 0. The format is as follows:

#include <omp.h>
int omp_get_thread_num(void);

If called from a serial region, omp_get_thread_num returns 0. If called from within a nested parallel region that is serialized, this function returns 0.

The omp_get_num_procs function returns the maximum number of processors that could be assigned to the program. The format is as follows:

#include <omp.h>
int omp_get_num_procs(void);

The omp_in_parallel function returns non-zero if it is called within the dynamic extent of a parallel region executing in parallel; otherwise, it returns 0. The format is as follows:

#include <omp.h>
int omp_in_parallel(void);

This function returns non-zero from within a region executing in parallel, regardless of nested regions that are serialized.

The omp_set_dynamic function enables or disables dynamic adjustment of the number of threads available for execution of parallel regions. The format is as follows:

#include <omp.h>
void omp_set_dynamic(int dynamic_threads);

This function has effect only when called from serial portions of the program. If it is called from a portion of the program where the omp_in_parallel function returns non-zero, the behavior of the function is undefined. If dynamic_threads evaluates to non-zero, the number of threads that are used for executing subsequent parallel regions may be adjusted automatically by the run-time environment to best utilize system resources. As a consequence, the number of threads specified by the user is the maximum thread count. The number of threads always remains fixed over the duration of each parallel region and is reported by the omp_get_num_threads function.

If dynamic_threads evaluates to 0, dynamic adjustment is disabled.

A call to omp_set_dynamic has precedence over the OMP_DYNAMIC environment variable.

The default for the dynamic adjustment of threads is implementation dependent. As a result, user codes that depend on a specific number of threads for correct execution should explicitly disable dynamic threads. Implementations are not required to provide the ability to dynamically adjust the number of threads, but they are required to provide the interface in order to support portability across all platforms.

The omp_get_dynamic function returns non-zero if dynamic thread adjustments enabled and returns 0 otherwise. For a description of dynamic thread adjustment, see omp_set_dynamic. The format is as follows:

#include <omp.h>
int omp_get_dynamic(void);

If the implementation does not implement dynamic adjustment of the number of threads, this function always returns 0.

The omp_set_nested function enables or disables nested parallelism. The format is as follows:

#include <omp.h>
void omp_set_nested(int nested);

If nested evaluates to 0, which is the default, nested parallelism is disabled, and nested parallel regions are serialized and executed by the current thread. If nested evaluates to non-zero, nested parallelism is enabled, and parallel regions that are nested may deploy additional threads to form the team.

This call has precedence over the OMP_NESTED environment variable.

When nested parallelism is enabled, the number of threads used to execute nested parallel regions is implementation dependent. As a result, OpenMP-compliant implementations are allowed to serialize nested parallel regions even when nested parallelism is enabled.

The omp_get_nested function returns non-zero if nested parallelism is enabled and 0 if it is disabled. The format is as follows:

#include <omp.h>
int omp_get_nested(void);

If an implementation does not implement nested parallelism, this function always returns 0.

These functions provide the only means of initializing a lock. Each function initializes the lock associated with the parameter lock for use in subsequent calls. The format is as follows:

#include <omp.h>
void omp_init_lock(omp_lock_t *lock);
void omp_init_nest_lock(omp_nest_lock_t *lock);

The initial state is unlocked (that is, no thread owns the lock). For a nestable lock, the initial nesting count is zero.

These functions ensure that the pointer to lock variable lock is uninitialized. The format is as follows:

#include <omp.h>
void omp_destroy_lock(omp_lock_t *lock);
void omp_destroy_nest_lock(omp_nest_lock_t *lock);

The argument to these functions must point to an initialized lock variable that is unlocked.

Each of these functions blocks the thread executing the function until the specified lock is available and then sets the lock. A simple lock is available if it is unlocked. A nestable lock is available if it is unlocked or if it is already owned by the thread executing the function. The format is as follows:

#include <omp.h>
void omp_set_lock(omp_lock_t *lock);
void omp_set_nest_lock(omp_nest_lock_t *lock);

For a simple lock, the argument to the omp_set_lock function must point to an initialized lock variable. Ownership of the lock is granted to the thread executing the function.

For a nestable lock, the argument to the omp_set_nest_lock function must point to an initialized lock variable. The nesting count is incremented, and the thread is granted, or retains, ownership of the lock.

These functions provide the means of releasing ownership of a lock. The format is as follows:

#include <omp.h>
void omp_unset_lock(omp_lock_t *lock);
void omp_unset_nest_lock(omp_nest_lock_t *lock);

The argument to each of these functions must point to an initialized lock variable owned by the thread executing the function. The behavior is undefined if the thread does not own that lock.

For a simple lock, the omp_unset_lock function releases the thread executing the function from ownership of the lock.

For a nestable lock, the omp_unset_nest_lock function decrements the nesting count, and releases the thread executing the function from ownership of the lock if the resulting count is zero.

These functions attempt to set a lock but do not block execution of the thread. The format is as follows:

#include <omp.h>
int omp_test_lock(omp_lock_t *lock);
int omp_test_nest_lock(omp_nest_lock_t *lock);

The argument must point to an initialized lock variable. These functions attempt to set a lock in the same manner as omp_set_lock and omp_set_nest_lock, except that they do not block execution of the thread.

For a simple lock, the omp_test_lock function returns non-zero if the lock is successfully set; otherwise, it returns zero.

For a nestable lock, the omp_test_nest_lock function returns the new nesting count if the lock is successfully set; otherwise, it returns zero.