OpenMP 函式

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

8
8
8
8
8

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

1
4
1
3
1

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_nestedOMP 巢狀平行處理原則，或藉由設定 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。