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	傳回值，這個值表示是否啟用巢狀平行處理原則。

針對鎖定：

函式	描述
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`	類型，保存下列其中一項有關鎖定的資訊：鎖定是否可用，以及擁有鎖定和巢狀計數之執行緒的身分識別。

針對計時常式：

函式	描述
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 巢狀平行處理原則，或藉由設定 OMP_NESTED 環境變數。

的設定 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_lock_t 變數，已使用 omp_init_lock 初始化，由執行緒擁有，並在函式中執行。

備註

如需詳細資訊，請參閱 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_nest_lock_t 變數，已使用 omp_init_nest_lock 初始化，由執行緒擁有並在函式中執行。

備註

如需詳細資訊，請參閱 3.2.4 omp_unset_lock 和 omp_unset_nest_lock 函式。

範例

如需使用 omp_unset_nest_lock 的範例，請參閱 omp_init_nest_lock 。

共用方式為

OpenMP 函式

omp_destroy_lock

參數

備註

範例

omp_destroy_nest_lock

參數

備註

範例

omp_get_dynamic

傳回值

備註

範例

omp_get_max_threads

備註

範例

omp_get_nested

傳回值

備註

範例

omp_get_num_procs

備註

範例

omp_get_num_threads

備註

範例

omp_get_thread_num

備註

範例

omp_get_wtick

備註

範例

omp_get_wtime

傳回值

備註

範例

omp_in_parallel

備註

範例

omp_init_lock

參數

備註

範例

omp_init_nest_lock

參數

備註

範例

omp_set_dynamic

參數

備註

範例

omp_set_lock

參數

備註

範例

omp_set_nest_lock

參數

備註

範例

omp_set_nested

參數

備註

範例

omp_set_num_threads

參數

備註

範例

omp_test_lock

參數

備註

範例

omp_test_nest_lock

參數

備註

範例

omp_unset_lock

參數

備註

範例