OpenMP 函数

项目
10/12/2023

提供 OpenMP API 中使用的函数的链接。

OpenMP 标准的 Visual C++ 实现包括以下函数和数据类型。

对于环境执行：

函数	说明
omp_set_num_threads	设置即将出现的并行区域中的线程数，除非由 num_threads 子句重写。
omp_get_num_threads	返回并行区域中的线程数。
omp_get_max_threads	如果在代码中的该位置定义了没有 num_threads 的并行区域，则返回等于或大于可用线程数的整数。
omp_get_thread_num	返回在其线程组中执行的线程的线程编号。
omp_get_num_procs	返回调用函数时可用的处理器数。
omp_in_parallel	如果从并行区域内调用，则返回非零值。
omp_set_dynamic	指示即将出现的并行区域中可用的线程数可由运行时调整。
omp_get_dynamic	返回一个值，指示即将出现的并行区域中可用的线程数是否可由运行时调整。
omp_set_nested	启用嵌套并行度。
omp_get_nested	返回一个值，指示是否启用了嵌套并行度。

对于锁：

Function	说明
omp_init_lock	初始化简单锁。
omp_init_nest_lock	初始化锁。
omp_destroy_lock	取消初始化锁。
omp_destroy_nest_lock	取消初始化嵌套锁。
omp_set_lock	阻塞线程执行，直到锁可用。
omp_set_nest_lock	阻塞线程执行，直到锁可用。
omp_unset_lock	释放锁。
omp_unset_nest_lock	释放可嵌套锁。
omp_test_lock	尝试设置锁但不阻塞线程执行。
omp_test_nest_lock	尝试设置可嵌套锁但不阻塞线程执行。

数据类型	描述
`omp_lock_t`	一个包含锁状态（锁是否可用，或线程是否拥有锁）的类型。
`omp_nest_lock_t`	一个包含有关锁的以下信息片段之一的类型：锁是否可用、拥有锁的线程的标识，以及嵌套计数。

对于计时例程：

Function	说明
omp_get_wtime	返回从某个时点开始算起已经过的时间（以秒为单位）的值。
omp_get_wtick	返回处理器时钟计时周期之间的秒数。

omp_destroy_lock

取消初始化锁。

void omp_destroy_lock(
   omp_lock_t *lock
);

参数

lock
使用 omp_init_lock 初始化的 omp_lock_t 类型的变量。

备注

有关详细信息，请参阅 3.2.2 omp_destroy_lock 和 omp_destroy_nest_lock 函数。

示例

有关使用 omp_destroy_lock 的示例，请参阅 omp_init_lock。

omp_destroy_nest_lock

取消初始化嵌套锁。

void omp_destroy_nest_lock(
   omp_nest_lock_t *lock
);

参数

lock
使用 omp_init_nest_lock 初始化的 omp_nest_lock_t 类型的变量。

备注

有关详细信息，请参阅 3.2.2 omp_destroy_lock 和 omp_destroy_nest_lock 函数。

示例

有关使用 omp_destroy_nest_lock 的示例，请参阅 omp_init_nest_lock。

omp_get_dynamic

返回一个值，指示即将出现的并行区域中可用的线程数是否可由运行时调整。

int omp_get_dynamic();

返回值

非零值表示线程将动态调整。

备注

使用 omp_set_dynamic 和 OMP_DYNAMIC 指定线程的动态调整。

有关详细信息，请参阅 3.1.7 omp_set_dynamic 函数。

示例

有关使用 omp_get_dynamic 的示例，请参阅 omp_set_dynamic。

omp_get_max_threads

如果在代码中的该位置定义了没有 num_threads 的并行区域，则返回等于或大于可用线程数的整数。

int omp_get_max_threads( )

注解

有关详细信息，请参阅 3.1.3 omp_get_max_threads 函数。

示例

// 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( ));
}

omp_get_nested

返回一个值，指示是否启用了嵌套并行度。

int omp_get_nested( );

返回值

非零值表示启用了嵌套并行度。

备注

嵌套并行度由 omp_set_nested 和 OMP_NESTED 指定。

有关详细信息，请参阅 3.1.10 omp_get_nested 函数。

示例

有关使用 omp_get_nested 的示例，请参阅 omp_set_nested。

omp_get_num_procs

返回调用函数时可用的处理器数。

int omp_get_num_procs();

备注

有关详细信息，请参阅 3.1.5 omp_get_num_procs 函数。

示例

// 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

返回并行区域中的线程数。

int omp_get_num_threads( );

备注

有关详细信息，请参阅 3.1.2 omp_get_num_threads 函数。

示例

// 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( ));
}

omp_get_thread_num

返回在其线程组中执行的线程的线程编号。

int omp_get_thread_num( );

备注

有关详细信息，请参阅 3.1.4 omp_get_thread_num 函数。

示例

有关使用 omp_get_thread_num 的示例，请参阅 parallel。

omp_get_wtick

返回处理器时钟计时周期之间的秒数。

double omp_get_wtick( );

备注

有关详细信息，请参阅 3.3.2 omp_get_wtick 函数。

示例

有关使用 omp_get_wtick 的示例，请参阅 omp_get_wtime。

omp_get_wtime

返回从某个时点开始算起已经过的时间（以秒为单位）的值。

double omp_get_wtime( );

返回值

返回从某个任意但一致的时点开始算起所经过的时间（以秒为单位）的值。

备注

该时点将在程序执行期间保持一致，使即将进行的比较成为可能。

有关详细信息，请参阅 3.3.1 omp_get_wtime 函数。

示例

// 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

如果从并行区域内调用，则返回非零值。

int omp_in_parallel( );

注解

有关详细信息，请参阅 3.1.6 omp_in_parallel 函数。

示例

// 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

初始化简单锁。

void omp_init_lock(
   omp_lock_t *lock
);

参数

lock
omp_lock_t 类型的变量。

备注

有关详细信息，请参阅 3.2.1 omp_init_lock 和 omp_init_nest_lock 函数。

示例

// 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

初始化锁。

void omp_init_nest_lock(
   omp_nest_lock_t *lock
);

参数

lock
omp_nest_lock_t 类型的变量。

注解

初始嵌套计数为零。

有关详细信息，请参阅 3.2.1 omp_init_lock 和 omp_init_nest_lock 函数。

示例

// 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

指示即将出现的并行区域中可用的线程数可由运行时调整。

void omp_set_dynamic(
   int val
);

参数

val
一个指示即将出现的并行区域中可用的线程数是否可由运行时调整的值。如果不为零，则运行时可以调整线程数；如果为零，则运行时不会动态调整线程数。

备注

线程数永远不会超过 omp_set_num_threads 或 OMP_NUM_THREADS 设置的值。

使用 omp_get_dynamic 显示 omp_set_dynamic 的当前设置。

omp_set_dynamic 的设置将重写 OMP_DYNAMIC 环境变量的设置。

有关详细信息，请参阅 3.1.7 omp_set_dynamic 函数。

示例

// 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

阻塞线程执行，直到锁可用。

void omp_set_lock(
   omp_lock_t *lock
);

参数

lock
使用 omp_init_lock 初始化的 omp_lock_t 类型的变量。

备注

有关详细信息，请参阅 3.2.3 omp_set_lock 和 omp_set_nest_lock 函数。

示例

有关使用 omp_set_lock 的示例，请参阅 omp_init_lock。

omp_set_nest_lock

阻塞线程执行，直到锁可用。

void omp_set_nest_lock(
   omp_nest_lock_t *lock
);

参数

lock
使用 omp_init_nest_lock 初始化的 omp_nest_lock_t 类型的变量。

注解

有关详细信息，请参阅 3.2.3 omp_set_lock 和 omp_set_nest_lock 函数。

示例

有关使用 omp_set_nest_lock 的示例，请参阅 omp_init_nest_lock。

omp_set_nested

启用嵌套并行度。

void omp_set_nested(
   int val
);

参数

val
如果值不为零，则启用嵌套并行度；如果为零，则禁用嵌套并行度。

备注

可以使用 omp_set_nested 或通过设置 OMP_NESTED 环境变量来打开 OMP 嵌套并行度。

omp_set_nested 的设置将重写 OMP_NESTED 环境变量的设置。

启用环境变量可能会破坏原本可以正常运行的程序，因为在嵌套并行区域时，线程数会呈指数级增长。例如，在 OMP 线程数设置为 4 的情况下递归六次的函数需要 4,096（4 的 6 次方）个线程。 I/O 密集型应用程序除外，如果线程数多于处理器数，则应用程序的性能通常会下降。

使用 omp_get_nested 显示 omp_set_nested 的当前设置。

有关详细信息，请参阅 3.1.9 omp_set_nested 函数。

示例

// 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

设置即将出现的并行区域中的线程数，除非由 num_threads 子句重写。

void omp_set_num_threads(
   int num_threads
);

参数

num_threads
并行区域中的线程数。

备注

有关详细信息，请参阅 3.1.1 omp_set_num_threads 函数。

示例

有关使用 omp_set_num_threads 的示例，请参阅 omp_get_num_threads。

omp_test_lock

尝试设置锁但不阻塞线程执行。

int omp_test_lock(
   omp_lock_t *lock
);

参数

lock
使用 omp_init_lock 初始化的 omp_lock_t 类型的变量。

备注

有关详细信息，请参阅 3.2.5 omp_test_lock 和 omp_test_nest_lock 函数。

示例

// 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

尝试设置可嵌套锁但不阻塞线程执行。

int omp_test_nest_lock(
   omp_nest_lock_t *lock
);

参数

lock
使用 omp_init_nest_lock 初始化的 omp_nest_lock_t 类型的变量。

备注

有关详细信息，请参阅 3.2.5 omp_test_lock 和 omp_test_nest_lock 函数。

示例

// 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

释放锁。

void omp_unset_lock(
   omp_lock_t *lock
);

参数

lock
使用 omp_init_lock 初始化的、由线程拥有并在函数中执行的类型 omp_lock_t 的变量。

备注

有关详细信息，请参阅 3.2.4 omp_unset_lock 和 omp_unset_nest_lock 函数。

示例

有关使用 omp_unset_lock 的示例，请参阅 omp_init_lock。

omp_unset_nest_lock

释放可嵌套锁。

void omp_unset_nest_lock(
   omp_nest_lock_t *lock
);

参数

lock
使用 omp_init_nest_lock 初始化的、由线程拥有并在函数中执行的类型 omp_nest_lock_t 的变量。

注解

有关详细信息，请参阅 3.2.4 omp_unset_lock 和 omp_unset_nest_lock 函数。

示例

有关使用 omp_unset_nest_lock 的示例，请参阅 omp_init_nest_lock。