Edit

OpenMP Functions

  • Article

Provides links to functions used in the OpenMP API.

The Visual C++ implementation of the OpenMP standard includes the following functions and data types.

For environment execution:

Function Description
omp_set_num_threads Sets the number of threads in upcoming parallel regions, unless overridden by a num_threads clause.
omp_get_num_threads Returns the number of threads in the parallel region.
omp_get_max_threads Returns an integer that is equal to or greater than the number of threads that would be available if a parallel region without num_threads were defined at that point in the code.
omp_get_thread_num Returns the thread number of the thread executing within its thread team.
omp_get_num_procs Returns the number of processors that are available when the function is called.
omp_in_parallel Returns nonzero if called from within a parallel region.
omp_set_dynamic Indicates that the number of threads available in upcoming parallel regions can be adjusted by the run time.
omp_get_dynamic Returns a value that indicates if the number of threads available in upcoming parallel regions can be adjusted by the run time.
omp_set_nested Enables nested parallelism.
omp_get_nested Returns a value that indicates if nested parallelism is enabled.

For lock:

Function Description
omp_init_lock Initializes a simple lock.
omp_init_nest_lock Initializes a lock.
omp_destroy_lock Uninitializes a lock.
omp_destroy_nest_lock Uninitializes a nestable lock.
omp_set_lock Blocks thread execution until a lock is available.
omp_set_nest_lock Blocks thread execution until a lock is available.
omp_unset_lock Releases a lock.
omp_unset_nest_lock Releases a nestable lock.
omp_test_lock Attempts to set a lock but doesn't block thread execution.
omp_test_nest_lock Attempts to set a nestable lock but doesn't block thread execution.
Data type Description
omp_lock_t A type that holds the status of a lock, whether the lock is available or if a thread owns a lock.
omp_nest_lock_t A type that holds one of the following pieces of information about a lock: whether the lock is available, and the identity of the thread that owns the lock and a nesting count.

For timing routines:

Function Description
omp_get_wtime Returns a value in seconds of the time elapsed from some point.
omp_get_wtick Returns the number of seconds between processor clock ticks.

omp_destroy_lock

Uninitializes a lock.

void omp_destroy_lock(
   omp_lock_t *lock
);

Parameters

lock
A variable of type omp_lock_t that was initialized with omp_init_lock.

Remarks

For more information, see 3.2.2 omp_destroy_lock and omp_destroy_nest_lock functions.

Example

See omp_init_lock for an example of using omp_destroy_lock.

omp_destroy_nest_lock

Uninitializes a nestable lock.

void omp_destroy_nest_lock(
   omp_nest_lock_t *lock
);

Parameters

lock
A variable of type omp_nest_lock_t that was initialized with omp_init_nest_lock.

Remarks

For more information, see 3.2.2 omp_destroy_lock and omp_destroy_nest_lock functions.

Example

See omp_init_nest_lock for an example of using omp_destroy_nest_lock.

omp_get_dynamic

Returns a value that indicates if the number of threads available in upcoming parallel regions can be adjusted by the run time.

int omp_get_dynamic();

Return value

A nonzero value means threads will be dynamically adjusted.

Remarks

Dynamic adjustment of threads is specified with omp_set_dynamic and OMP_DYNAMIC.

For more information, see 3.1.7 omp_set_dynamic function.

Example

See omp_set_dynamic for an example of using omp_get_dynamic.

omp_get_max_threads

Returns an integer that is equal to or greater than the number of threads that would be available if a parallel region without num_threads were defined at that point in the code.

int omp_get_max_threads( )

Remarks

For more information, see 3.1.3 omp_get_max_threads function.

Example

// omp_get_max_threads.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

int main( )
{
    omp_set_num_threads(8);
    printf_s("%d\n", omp_get_max_threads( ));
    #pragma omp parallel
        #pragma omp master
        {
            printf_s("%d\n", omp_get_max_threads( ));
        }

    printf_s("%d\n", omp_get_max_threads( ));

    #pragma omp parallel num_threads(3)
        #pragma omp master
        {
            printf_s("%d\n", omp_get_max_threads( ));
        }

    printf_s("%d\n", omp_get_max_threads( ));
}

8
8
8
8
8

omp_get_nested

Returns a value that indicates if nested parallelism is enabled.

int omp_get_nested( );

Return value

A nonzero value means nested parallelism is enabled.

Remarks

Nested parallelism is specified with omp_set_nested and OMP_NESTED.

For more information, see 3.1.10 omp_get_nested function.

Example

See omp_set_nested for an example of using omp_get_nested.

omp_get_num_procs

Returns the number of processors that are available when the function is called.

int omp_get_num_procs();

Remarks

For more information, see 3.1.5 omp_get_num_procs function.

Example

// omp_get_num_procs.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

int main( )
{
    printf_s("%d\n", omp_get_num_procs( ));
    #pragma omp parallel
        #pragma omp master
        {
            printf_s("%d\n", omp_get_num_procs( ));
        }
}

// Expect the following output when the example is run on a two-processor machine:
2
2

omp_get_num_threads

Returns the number of threads in the parallel region.

int omp_get_num_threads( );

Remarks

For more information, see 3.1.2 omp_get_num_threads function.

Example

// omp_get_num_threads.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

int main()
{
    omp_set_num_threads(4);
    printf_s("%d\n", omp_get_num_threads( ));
    #pragma omp parallel
        #pragma omp master
        {
            printf_s("%d\n", omp_get_num_threads( ));
        }

    printf_s("%d\n", omp_get_num_threads( ));

    #pragma omp parallel num_threads(3)
        #pragma omp master
        {
            printf_s("%d\n", omp_get_num_threads( ));
        }

    printf_s("%d\n", omp_get_num_threads( ));
}

1
4
1
3
1

omp_get_thread_num

Returns the thread number of the thread executing within its thread team.

int omp_get_thread_num( );

Remarks

For more information, see 3.1.4 omp_get_thread_num function.

Example

See parallel for an example of using omp_get_thread_num.

omp_get_wtick

Returns the number of seconds between processor clock ticks.

double omp_get_wtick( );

Remarks

For more information, see 3.3.2 omp_get_wtick function.

Example

See omp_get_wtime for an example of using omp_get_wtick.

omp_get_wtime

Returns a value in seconds of the time elapsed from some point.

double omp_get_wtime( );

Return value

Returns a value in seconds of the time elapsed from some arbitrary, but consistent point.

Remarks

That point will remain consistent during program execution, making upcoming comparisons possible.

For more information, see 3.3.1 omp_get_wtime function.

Example

// omp_get_wtime.cpp
// compile with: /openmp
#include "omp.h"
#include <stdio.h>
#include <windows.h>

int main() {
    double start = omp_get_wtime( );
    Sleep(1000);
    double end = omp_get_wtime( );
    double wtick = omp_get_wtick( );

    printf_s("start = %.16g\nend = %.16g\ndiff = %.16g\n",
             start, end, end - start);

    printf_s("wtick = %.16g\n1/wtick = %.16g\n",
             wtick, 1.0 / wtick);
}

start = 594255.3671159324
end = 594256.3664474116
diff = 0.9993314791936427
wtick = 2.793651148400146e-007
1/wtick = 3579545

omp_in_parallel

Returns nonzero if called from within a parallel region.

int omp_in_parallel( );

Remarks

For more information, see 3.1.6 omp_in_parallel function.

Example

// omp_in_parallel.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

int main( )
{
    omp_set_num_threads(4);
    printf_s("%d\n", omp_in_parallel( ));

    #pragma omp parallel
        #pragma omp master
        {
            printf_s("%d\n", omp_in_parallel( ));
        }
}

0
1

omp_init_lock

Initializes a simple lock.

void omp_init_lock(
   omp_lock_t *lock
);

Parameters

lock
A variable of type omp_lock_t.

Remarks

For more information, see 3.2.1 omp_init_lock and omp_init_nest_lock functions.

Example

// omp_init_lock.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

omp_lock_t my_lock;

int main() {
   omp_init_lock(&my_lock);

   #pragma omp parallel num_threads(4)
   {
      int tid = omp_get_thread_num( );
      int i, j;

      for (i = 0; i < 5; ++i) {
         omp_set_lock(&my_lock);
         printf_s("Thread %d - starting locked region\n", tid);
         printf_s("Thread %d - ending locked region\n", tid);
         omp_unset_lock(&my_lock);
      }
   }

   omp_destroy_lock(&my_lock);
}

Thread 0 - starting locked region
Thread 0 - ending locked region
Thread 0 - starting locked region
Thread 0 - ending locked region
Thread 0 - starting locked region
Thread 0 - ending locked region
Thread 0 - starting locked region
Thread 0 - ending locked region
Thread 0 - starting locked region
Thread 0 - ending locked region
Thread 1 - starting locked region
Thread 1 - ending locked region
Thread 1 - starting locked region
Thread 1 - ending locked region
Thread 1 - starting locked region
Thread 1 - ending locked region
Thread 1 - starting locked region
Thread 1 - ending locked region
Thread 1 - starting locked region
Thread 1 - ending locked region
Thread 2 - starting locked region
Thread 2 - ending locked region
Thread 2 - starting locked region
Thread 2 - ending locked region
Thread 2 - starting locked region
Thread 2 - ending locked region
Thread 2 - starting locked region
Thread 2 - ending locked region
Thread 2 - starting locked region
Thread 2 - ending locked region
Thread 3 - starting locked region
Thread 3 - ending locked region
Thread 3 - starting locked region
Thread 3 - ending locked region
Thread 3 - starting locked region
Thread 3 - ending locked region
Thread 3 - starting locked region
Thread 3 - ending locked region
Thread 3 - starting locked region
Thread 3 - ending locked region

omp_init_nest_lock

Initializes a lock.

void omp_init_nest_lock(
   omp_nest_lock_t *lock
);

Parameters

lock
A variable of type omp_nest_lock_t.

Remarks

The initial nesting count is zero.

For more information, see 3.2.1 omp_init_lock and omp_init_nest_lock functions.

Example

// omp_init_nest_lock.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

omp_nest_lock_t my_lock;

void Test() {
   int tid = omp_get_thread_num( );
   omp_set_nest_lock(&my_lock);
   printf_s("Thread %d - starting nested locked region\n", tid);
   printf_s("Thread %d - ending nested locked region\n", tid);
   omp_unset_nest_lock(&my_lock);
}

int main() {
   omp_init_nest_lock(&my_lock);

   #pragma omp parallel num_threads(4)
   {
      int i, j;

      for (i = 0; i < 5; ++i) {
         omp_set_nest_lock(&my_lock);
            if (i % 3)
               Test();
            omp_unset_nest_lock(&my_lock);
        }
    }

    omp_destroy_nest_lock(&my_lock);
}

Thread 0 - starting nested locked region
Thread 0 - ending nested locked region
Thread 0 - starting nested locked region
Thread 0 - ending nested locked region
Thread 3 - starting nested locked region
Thread 3 - ending nested locked region
Thread 3 - starting nested locked region
Thread 3 - ending nested locked region
Thread 3 - starting nested locked region
Thread 3 - ending nested locked region
Thread 2 - starting nested locked region
Thread 2 - ending nested locked region
Thread 2 - starting nested locked region
Thread 2 - ending nested locked region
Thread 2 - starting nested locked region
Thread 2 - ending nested locked region
Thread 1 - starting nested locked region
Thread 1 - ending nested locked region
Thread 1 - starting nested locked region
Thread 1 - ending nested locked region
Thread 1 - starting nested locked region
Thread 1 - ending nested locked region
Thread 0 - starting nested locked region
Thread 0 - ending nested locked region

omp_set_dynamic

Indicates that the number of threads available in upcoming parallel regions can be adjusted by the run time.

void omp_set_dynamic(
   int val
);

Parameters

val
A value that indicates if the number of threads available in upcoming parallel regions can be adjusted by the runtime. If nonzero, the runtime can adjust the number of threads, if zero, the runtime won't dynamically adjust the number of threads.

Remarks

The number of threads will never exceed the value set by omp_set_num_threads or by OMP_NUM_THREADS.

Use omp_get_dynamic to display the current setting of omp_set_dynamic.

The setting for omp_set_dynamic will override the setting of the OMP_DYNAMIC environment variable.

For more information, see 3.1.7 omp_set_dynamic function.

Example

// omp_set_dynamic.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

int main()
{
    omp_set_dynamic(9);
    omp_set_num_threads(4);
    printf_s("%d\n", omp_get_dynamic( ));
    #pragma omp parallel
        #pragma omp master
        {
            printf_s("%d\n", omp_get_dynamic( ));
        }
}

1
1

omp_set_lock

Blocks thread execution until a lock is available.

void omp_set_lock(
   omp_lock_t *lock
);

Parameters

lock
A variable of type omp_lock_t that was initialized with omp_init_lock.

Remarks

For more information, see 3.2.3 omp_set_lock and omp_set_nest_lock functions.

Examples

See omp_init_lock for an example of using omp_set_lock.

omp_set_nest_lock

Blocks thread execution until a lock is available.

void omp_set_nest_lock(
   omp_nest_lock_t *lock
);

Parameters

lock
A variable of type omp_nest_lock_t that was initialized with omp_init_nest_lock.

Remarks

For more information, see 3.2.3 omp_set_lock and omp_set_nest_lock functions.

Examples

See omp_init_nest_lock for an example of using omp_set_nest_lock.

omp_set_nested

Enables nested parallelism.

void omp_set_nested(
   int val
);

Parameters

val
A nonzero value enables nested parallelism, while zero disables nested parallelism.

Remarks

OMP nested parallelism can be turned on with omp_set_nested, or by setting the OMP_NESTED environment variable.

The setting for omp_set_nested will override the setting of the OMP_NESTED environment variable.

Enabling the environment variable can break an otherwise operational program, because the number of threads increases exponentially when nesting parallel regions. For example, a function that recurses six times with the number of OMP threads set to 4 requires 4,096 (4 to the power of 6) threads. Except with I/O-bound applications, the performance of an application generally degrades if there are more threads than processors.

Use omp_get_nested to display the current setting of omp_set_nested.

For more information, see 3.1.9 omp_set_nested function.

Example

// omp_set_nested.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

int main( )
{
    omp_set_nested(1);
    omp_set_num_threads(4);
    printf_s("%d\n", omp_get_nested( ));
    #pragma omp parallel
        #pragma omp master
        {
            printf_s("%d\n", omp_get_nested( ));
        }
}

1
1

omp_set_num_threads

Sets the number of threads in upcoming parallel regions, unless overridden by a num_threads clause.

void omp_set_num_threads(
   int num_threads
);

Parameters

num_threads
The number of threads in the parallel region.

Remarks

For more information, see 3.1.1 omp_set_num_threads function.

Example

See omp_get_num_threads for an example of using omp_set_num_threads.

omp_test_lock

Attempts to set a lock but doesn't block thread execution.

int omp_test_lock(
   omp_lock_t *lock
);

Parameters

lock
A variable of type omp_lock_t that was initialized with omp_init_lock.

Remarks

For more information, see 3.2.5 omp_test_lock and omp_test_nest_lock functions.

Example

// omp_test_lock.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

omp_lock_t simple_lock;

int main() {
    omp_init_lock(&simple_lock);

    #pragma omp parallel num_threads(4)
    {
        int tid = omp_get_thread_num();

        while (!omp_test_lock(&simple_lock))
            printf_s("Thread %d - failed to acquire simple_lock\n",
                     tid);

        printf_s("Thread %d - acquired simple_lock\n", tid);

        printf_s("Thread %d - released simple_lock\n", tid);
        omp_unset_lock(&simple_lock);
    }

    omp_destroy_lock(&simple_lock);
}

Thread 1 - acquired simple_lock
Thread 1 - released simple_lock
Thread 0 - failed to acquire simple_lock
Thread 3 - failed to acquire simple_lock
Thread 0 - failed to acquire simple_lock
Thread 3 - failed to acquire simple_lock
Thread 2 - acquired simple_lock
Thread 0 - failed to acquire simple_lock
Thread 3 - failed to acquire simple_lock
Thread 0 - failed to acquire simple_lock
Thread 3 - failed to acquire simple_lock
Thread 2 - released simple_lock
Thread 0 - failed to acquire simple_lock
Thread 3 - failed to acquire simple_lock
Thread 0 - acquired simple_lock
Thread 3 - failed to acquire simple_lock
Thread 0 - released simple_lock
Thread 3 - failed to acquire simple_lock
Thread 3 - acquired simple_lock
Thread 3 - released simple_lock

omp_test_nest_lock

Attempts to set a nestable lock but doesn't block thread execution.

int omp_test_nest_lock(
   omp_nest_lock_t *lock
);

Parameters

lock
A variable of type omp_nest_lock_t that was initialized with omp_init_nest_lock.

Remarks

For more information, see 3.2.5 omp_test_lock and omp_test_nest_lock functions.

Example

// omp_test_nest_lock.cpp
// compile with: /openmp
#include <stdio.h>
#include <omp.h>

omp_nest_lock_t nestable_lock;

int main() {
   omp_init_nest_lock(&nestable_lock);

   #pragma omp parallel num_threads(4)
   {
      int tid = omp_get_thread_num();
      while (!omp_test_nest_lock(&nestable_lock))
         printf_s("Thread %d - failed to acquire nestable_lock\n",
                tid);

      printf_s("Thread %d - acquired nestable_lock\n", tid);

      if (omp_test_nest_lock(&nestable_lock)) {
         printf_s("Thread %d - acquired nestable_lock again\n",
                tid);
         printf_s("Thread %d - released nestable_lock\n",
                tid);
         omp_unset_nest_lock(&nestable_lock);
      }

      printf_s("Thread %d - released nestable_lock\n", tid);
      omp_unset_nest_lock(&nestable_lock);
   }

   omp_destroy_nest_lock(&nestable_lock);
}

Thread 1 - acquired nestable_lock
Thread 0 - failed to acquire nestable_lock
Thread 1 - acquired nestable_lock again
Thread 0 - failed to acquire nestable_lock
Thread 1 - released nestable_lock
Thread 0 - failed to acquire nestable_lock
Thread 1 - released nestable_lock
Thread 0 - failed to acquire nestable_lock
Thread 3 - acquired nestable_lock
Thread 0 - failed to acquire nestable_lock
Thread 3 - acquired nestable_lock again
Thread 0 - failed to acquire nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 3 - released nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 3 - released nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 0 - acquired nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 0 - acquired nestable_lock again
Thread 2 - failed to acquire nestable_lock
Thread 0 - released nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 0 - released nestable_lock
Thread 2 - failed to acquire nestable_lock
Thread 2 - acquired nestable_lock
Thread 2 - acquired nestable_lock again
Thread 2 - released nestable_lock
Thread 2 - released nestable_lock

omp_unset_lock

Releases a lock.

void omp_unset_lock(
   omp_lock_t *lock
);

Parameters

lock
A variable of type omp_lock_t that was initialized with omp_init_lock, owned by the thread and executing in the function.

Remarks

For more information, see 3.2.4 omp_unset_lock and omp_unset_nest_lock functions.

Example

See omp_init_lock for an example of using omp_unset_lock.

omp_unset_nest_lock

Releases a nestable lock.

void omp_unset_nest_lock(
   omp_nest_lock_t *lock
);

Parameters

lock
A variable of type omp_nest_lock_t that was initialized with omp_init_nest_lock, owned by the thread and executing in the function.

Remarks

For more information, see 3.2.4 omp_unset_lock and omp_unset_nest_lock functions.

Example

See omp_init_nest_lock for an example of using omp_unset_nest_lock.