# Parallel notes N4 \- continuing to study OpenMP constructs

In this post we will continue to introduce you into OpenMP technology and tell you about some functions and new directives\.

[OpenMP](https://pvs-studio.com/en/blog/posts/a0057/) has some auxiliary functions\. Do not forget to enable the header file <omp\.h\> to be able to use them\.\.

## Execution environment functions

These functions allow you to request for and set various parameters of the OpenMP environment:

* omp\_get\_num\_procs returns the number of the computational nodes \(processors/cores\) in the computer\.
* omp\_in\_parallel allows a [thread](https://pvs-studio.com/en/blog/terms/0048/) to know if it is processing a parallel region at the moment\.
* omp\_get\_num\_threads returns the number of threads included into the current thread team\.
* omp\_set\_num\_thread defines the number of threads to execute the next parallel region the current executed thread will meet\. The function may help you distribute resources\. For example, if you are simultaneously processing sound and video on one processor with four cores, you may create one thread to process the sound and three threads to process the video\.
* omp\_get\_max\_threads returns the maximum possible number of threads to be used in the next parallel region\.
* omp\_set\_nested permits or forbids nested parallelism\. If nested parallelism is permitted, each thread that has a description of a parallel region will spawn a new thread team to execute this region and will become the master\-thread of the team\.
* omp\_get\_nested tells you if nested parallelism is enabled or disabled\.

If the name of a function begins with omp\_set\_, it may be called only outside parallel regions\. All the rest functions may be used both inside and outside parallel regions\.

## Synchronization/lock functions

OpenMP allows you to build parallel code without these functions because there are directives that implement some synchronization types\. But in some cases these functions are convenient and even necessary\.

OpenMP has two types of locks: simple and nested\. The locks of the latter type have the suffix "nest"\. Locks may be in one of the three states \- non\-initialized, locked and unlocked\.

* omp\_init\_lock/omp\_init\_nest\_lock serves to initialize a variable of the type omp\_lock\_t/omp\_nest\_lock\_t\. It is equivalent to InitializeCriticalSection\.
* omp\_destroy\_lock/omp\_destroy\_nest\_lock serves to unlock a variable of the type omp\_lock\_t/omp\_nest\_lock\_t\. It is equivalent to DeleteCriticalSection\.
* omp\_set\_lock/omp\_set\_nest\_lock \- when this lock is used, one thread sets the lock while the others wait for it to unlock the variable with the function omp\_unset\_lock\(\)\. It is equivalent to EnterCriticalSection\.
* omp\_unset\_lock/omp\_unset\_nest\_lock is used to release the lock\. It is equivalent to LeaveCriticalSection\.
* omp\_test\_lock/omp\_test\_nest\_lock is a non\-locking attempt to capture a lock\. This function will try to capture the specified lock\. If it succeeds, it will return 1 for a simple lock\. If it fails, it will return 0\. It is equivalent to TryEnterCriticalSection\.

Simple locks cannot be set more than once even by the same thread\. Nested locks are nearly the same as simple ones with the exception that a thread is not locked when trying to set a nested lock already belonging to it\.

Here is an example of code where these functions are used\. All the threads being created will by turn print the messages "Begin work" and "End work"\. Between these two messages generated by one thread there may appear messages from the other threads generated when they fail to enter a locked section\.

```cpp
omp_lock_t lock;
int n;
omp_init_lock(&lock);
#pragma omp parallel private (n)
{
  n=omp_get_thread_num();
  while (!omp_test_lock (&lock))
  {
    printf("Wait..., thread %d\n", n);
    Sleep(3);
  }
  printf("Begin work, thread %d\n", n);
  Sleep(5); // Work...
  printf("End work, thread %d\n", n);
  omp_unset_lock(&lock);
}
omp_destroy_lock(&lock);
```

You may expect the following result on a computer with four cores:

Begin work, thread 0

 Wait\.\.\., thread 1

 Wait\.\.\., thread 2

 Wait\.\.\., thread 3

 Wait\.\.\., thread 2

 Wait\.\.\., thread 3

 Wait\.\.\., thread 1

 End work, thread 0

 Begin work, thread 2

 Wait\.\.\., thread 3

 Wait\.\.\., thread 1

 Wait\.\.\., thread 3

 Wait\.\.\., thread 1

 End work, thread 2

 Begin work, thread 3

 Wait\.\.\., thread 1

 Wait\.\.\., thread 1

 End work, thread 3

 Begin work, thread 1

 End work, thread 1

## Timer functions

* omp\_get\_wtime returns the astronomical time that has passed since some moment in past in seconds in the thread that has called it \(a real number of double precision \- double\)\. If you surround some code fragment with calls of this function, the remainder of the values being returned will show the time of this fragment's execution\.
* omp\_get\_wtick\(\) returns the resolution of the timer in seconds in the thread that has called it, i\.e\. shows the timer's precision\.

Let us finish here with the functions and consider a couple of new directives\. These directives may be called options of the parallel regions being created\.

## if \(condition\)

Execution of a parallel region by a condition\. Several threads are created only if some condition is fulfilled\. Otherwise the code continues to execute in serial mode\.

For example:

```cpp
void test(bool x)
{
  #pragma omp parallel if (x)
  if (omp_in_parallel())
  {
    #pragma omp single
    printf_s("parallelized with %d threads\n",
             omp_get_num_threads());
  }
  else
  {
    printf_s("single thread\n");
  }
}
int _tmain(int argc, _TCHAR* argv[])
{
  test(false);
  test(true);
  return 0;
}
```

The result:

```cpp
single thread
parallelized with 4 threads
```

## num\_threads

It serves to explicitly define the number of threads to execute a parallel region\. By default, the last value is selected that was returned by the function omp\_set\_num\_threads\(\)\.

If we modify the example above in the following way:

```cpp
...
#pragma omp parallel if (x) num_threads(3)
...
```

the result will be the following:

```cpp
single thread
parallelized with 3 threads
```

To be continued in the next issue of "Parallel Notes"\.\.\.