Funções (OpenMP)

Artigo
06/16/2023

Fornece links para as funções usadas na API OpenMP.

A implementação do Visual C++ do padrão OpenMP inclui as funções e os tipos de dados a seguir.

Para execução do ambiente:

Função	Descrição
omp_set_num_threads	Define o número de threads em regiões paralelas futuras, a menos que seja substituído por uma cláusula num_threads.
omp_get_num_threads	Retorna o número de threads na região paralela.
omp_get_max_threads	Retorna um inteiro igual ou maior que o número de threads que estariam disponíveis se uma região paralela sem num_threads fosse definida nesse ponto no código.
omp_get_thread_num	Retorna o número de threads do thread em execução em sua equipe de threads.
omp_get_num_procs	Retorna o número de processadores que estão disponíveis quando a função é chamada.
omp_in_parallel	Retorna não zero se chamado de dentro de uma região paralela.
omp_set_dynamic	Indica que o número de threads disponíveis em regiões paralelas futuras pode ser ajustado pelo tempo de execução.
omp_get_dynamic	Retorna um valor que indica se o número de threads disponíveis em regiões paralelas futuras pode ser ajustado pelo tempo de execução.
omp_set_nested	Habilita o paralelismo aninhado.
omp_get_nested	Retorna um valor que indica se o paralelismo aninhado está habilitado.

Para bloqueio:

Função	Descrição
omp_init_lock	Inicializa um bloqueio simples.
omp_init_nest_lock	Inicializa um bloqueio.
omp_destroy_lock	Cancela a inicialização de um bloqueio.
omp_destroy_nest_lock	Não diferencia um bloqueio aninhável.
omp_set_lock	Bloqueia a execução do thread até que um bloqueio esteja disponível.
omp_set_nest_lock	Bloqueia a execução do thread até que um bloqueio esteja disponível.
omp_unset_lock	Libera um bloqueio.
omp_unset_nest_lock	Libera um bloqueio aninhável.
omp_test_lock	Tenta definir um bloqueio, mas não bloqueia a execução do thread.
omp_test_nest_lock	Tenta definir um bloqueio aninhável, mas não bloqueia a execução do thread.

Tipo de dados	Descrição
`omp_lock_t`	Um tipo que conterá o status de um bloqueio, se o bloqueio estiver disponível ou se um thread possuir um bloqueio.
`omp_nest_lock_t`	Um tipo que contém uma das seguintes informações sobre um bloqueio: se o bloqueio está disponível, e a identidade do thread que possui o bloqueio e uma contagem de aninhamento.

Para rotinas de tempo:

Função	Descrição
omp_get_wtime	Retorna um valor em segundos do tempo decorrido de algum ponto.
omp_get_wtick	Retorna o número de segundos entre os acionamentos do clock do processador.

omp_destroy_lock

Cancela a inicialização de um bloqueio.

void omp_destroy_lock(
   omp_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_lock_t que foi inicializada com omp_init_lock.

Comentários

Para obter mais informações, consulte 3.2.2 Funções omp_destroy_lock e omp_destroy_nest_lock.

Exemplo

Consulte omp_init_lock para obter um exemplo de uso de omp_destroy_lock.

omp_destroy_nest_lock

Não diferencia um bloqueio aninhável.

void omp_destroy_nest_lock(
   omp_nest_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_nest_lock_t que foi inicializada com omp_init_nest_lock.

Comentários

Para obter mais informações, consulte 3.2.2 Funções omp_destroy_lock e omp_destroy_nest_lock.

Exemplo

Consulte omp_init_nest_lock para obter um exemplo de uso de omp_destroy_nest_lock.

omp_get_dynamic

Retorna um valor que indica se o número de threads disponíveis em regiões paralelas futuras pode ser ajustado pelo tempo de execução.

int omp_get_dynamic();

Retornar valor

Um valor não zero significa que os threads serão ajustados dinamicamente.

Comentários

O ajuste dinâmico de threads é especificado com omp_set_dynamic e OMP_DYNAMIC.

Para obter mais informações, confira 3.1.7 Função omp_set_dynamic.

Exemplo

Consulte omp_set_dynamic para obter um exemplo de uso de omp_get_dynamic.

omp_get_max_threads

Retorna um inteiro igual ou maior que o número de threads que estariam disponíveis se uma região paralela sem num_threads fosse definida nesse ponto no código.

int omp_get_max_threads( )

Comentários

Para obter mais informações, confira 3.1.3 Função omp_get_max_threads.

Exemplo

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

Retorna um valor que indica se o paralelismo aninhado está habilitado.

int omp_get_nested( );

Retornar valor

Um valor não zero significa que o paralelismo aninhado está habilitado.

Comentários

O paralelismo aninhado é especificado com omp_set_nested e OMP_NESTED.

Para obter mais informações, confira 3.1.10 Função omp_get_nested.

Exemplo

Consulte omp_set_nested para obter um exemplo de uso de omp_get_nested.

omp_get_num_procs

Retorna o número de processadores que estão disponíveis quando a função é chamada.

int omp_get_num_procs();

Comentários

Para obter mais informações, confira 3.1.5 Função omp_get_num_procs.

Exemplo

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

Retorna o número de threads na região paralela.

int omp_get_num_threads( );

Comentários

Para obter mais informações, confira 3.1.2 Função omp_get_max_threads.

Exemplo

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

Retorna o número de threads do thread em execução em sua equipe de threads.

int omp_get_thread_num( );

Comentários

Para obter mais informações, confira 3.1.4 Função omp_get_thread_num.

Exemplo

Consulte paralelo para obter um exemplo de uso de omp_get_thread_num.

omp_get_wtick

Retorna o número de segundos entre os acionamentos do clock do processador.

double omp_get_wtick( );

Comentários

Para obter mais informações, confira 3.3.2 Função omp_get_wtick.

Exemplo

Consulte omp_get_wtime para obter um exemplo de uso omp_get_wtick.

omp_get_wtime

Retorna um valor em segundos do tempo decorrido de algum ponto.

double omp_get_wtime( );

Retornar valor

Retorna um valor em segundos do tempo decorrido de algum ponto arbitrário, mas consistente.

Comentários

Esse ponto permanecerá consistente durante a execução do programa, tornando as comparações futuras possíveis.

Para obter mais informações, confira 3.3.1 Função omp_get_wtime.

Exemplo

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

Retorna não zero se chamado de dentro de uma região paralela.

int omp_in_parallel( );

Comentários

Para obter mais informações, confira 3.1.6 Função omp_in_parallel.

Exemplo

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

Inicializa um bloqueio simples.

void omp_init_lock(
   omp_lock_t *lock
);

Parâmetros

lock
Uma variável do tipo omp_lock_t.

Comentários

Para obter mais informações, consulte 3.2.1 Funções omp_init_lock e omp_init_nest_lock.

Exemplo

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

Inicializa um bloqueio.

void omp_init_nest_lock(
   omp_nest_lock_t *lock
);

Parâmetros

lock
Uma variável do tipo omp_nest_lock_t.

Comentários

A contagem inicial de aninhamento é zero.

Para obter mais informações, consulte 3.2.1 Funções omp_init_lock e omp_init_nest_lock.

Exemplo

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

Indica que o número de threads disponíveis em regiões paralelas futuras pode ser ajustado pelo tempo de execução.

void omp_set_dynamic(
   int val
);

Parâmetros

val
Um valor que indica se o número de threads disponíveis em regiões paralelas futuras pode ser ajustado pelo tempo de execução. Se não for zero, o runtime poderá ajustar o número de threads, se zero, o runtime não ajustará dinamicamente o número de threads.

Comentários

O número de threads nunca excederá o valor definido por omp_set_num_threads ou por OMP_NUM_THREADS.

Use omp_get_dynamic para exibir a configuração atual de omp_set_dynamic.

A configuração para omp_set_dynamic substituirá a configuração da variável de ambiente OMP_DYNAMIC.

Para obter mais informações, confira 3.1.7 Função omp_set_dynamic.

Exemplo

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

Bloqueia a execução do thread até que um bloqueio esteja disponível.

void omp_set_lock(
   omp_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_lock_t que foi inicializada com omp_init_lock.

Comentários

Para obter mais informações, consulte 3.2.3 Funções omp_set_lock e omp_set_nest_lock.

Exemplos

Consulte omp_init_lock para obter um exemplo de uso de omp_set_lock.

omp_set_nest_lock

Bloqueia a execução do thread até que um bloqueio esteja disponível.

void omp_set_nest_lock(
   omp_nest_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_nest_lock_t que foi inicializada com omp_init_nest_lock.

Comentários

Para obter mais informações, consulte 3.2.3 Funções omp_set_lock e omp_set_nest_lock.

Exemplos

Consulte omp_init_nest_lock para obter um exemplo de uso de omp_set_nest_lock.

omp_set_nested

Habilita o paralelismo aninhado.

void omp_set_nested(
   int val
);

Parâmetros

val
Um valor não zero habilita o paralelismo aninhado, enquanto zero desabilita o paralelismo aninhado.

Comentários

O paralelismo aninhado do OMP pode ser ativado com omp_set_nested ou definindo a variável de ambiente OMP_NESTED.

A configuração para omp_set_nested substituirá a configuração da variável de ambiente OMP_NESTED.

Habilitar a variável de ambiente pode interromper um programa operacional de outra forma, pois o número de threads aumenta exponencialmente ao aninhar regiões paralelas. Por exemplo, uma função que se recursa seis vezes com o número de threads OMP definidos como 4 requer 4.096 (4 elevado à potência 6) threads. Exceto com aplicativos associados a E/S, o desempenho de um aplicativo geralmente cairá se houver mais threads do que processadores.

Use omp_get_nested para exibir a configuração atual de omp_set_nested.

Para obter mais informações, confira 3.1.9 Função omp_set_nested.

Exemplo

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

Define o número de threads em regiões paralelas futuras, a menos que seja substituído por uma cláusula num_threads.

void omp_set_num_threads(
   int num_threads
);

Parâmetros

num_threads
O número de threads na região paralela.

Comentários

Para obter mais informações, confira 3.1.1 Função omp_set_max_threads.

Exemplo

Consulte omp_get_num_threads para obter um exemplo de uso de omp_set_num_threads.

omp_test_lock

Tenta definir um bloqueio, mas não bloqueia a execução do thread.

int omp_test_lock(
   omp_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_lock_t que foi inicializada com omp_init_lock.

Comentários

Para obter mais informações, consulte 3.2.5 Funções omp_test_lock e omp_test_nest_lock.

Exemplo

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

Tenta definir um bloqueio aninhável, mas não bloqueia a execução do thread.

int omp_test_nest_lock(
   omp_nest_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_nest_lock_t que foi inicializada com omp_init_nest_lock.

Comentários

Para obter mais informações, consulte 3.2.5 Funções omp_test_lock e omp_test_nest_lock.

Exemplo

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

Libera um bloqueio.

void omp_unset_lock(
   omp_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_lock_t que foi inicializada com omp_init_lock, pertencente ao thread e em execução na função.

Comentários

Para obter mais informações, consulte 3.2.4 Funções omp_unset_lock e omp_unset_nest_lock.

Exemplo

Consulte omp_init_lock para obter um exemplo de uso de omp_unset_lock.

omp_unset_nest_lock

Libera um bloqueio aninhável.

void omp_unset_nest_lock(
   omp_nest_lock_t *lock
);

Parâmetros

lock
Uma variável de tipo omp_nest_lock_t que foi inicializada com omp_init_nest_lock, pertencente ao thread e em execução na função.

Comentários

Para obter mais informações, consulte 3.2.4 Funções omp_unset_lock e omp_unset_nest_lock.

Exemplo

Consulte omp_init_nest_lock para obter um exemplo de uso de omp_unset_nest_lock.