#pragma omp cancel

Purpose

The omp cancel directive activates the cancellation of the innermost enclosing region of the specified type.

Syntax


>>-#--pragma--omp cancel--type_clause--+---+--+-------------------------+-><
                                       '-,-'  '-if--(scalar-expression)-'

where type_clause is:


>>-+-parallel--+-----------------------------------------------><
   +-sections--+   
   +-for-------+   
   '-taskgroup-'

Usage

The omp cancel directive is a stand-alone directive. The binding thread set of the cancel region is the current team, and the binding region is the innermost enclosing region of the type that is specified in type_clause. The cancellation model is enabled only when the OMP_CANCELLATION environment variable is set to true. If the cancellation model is enabled, omp cancel activates the cancellation of the binding region; otherwise, the directive is ignored.

The compiler implicitly adds cancellation points at the following program directives or regions:

The omp cancel directives
Implicit or explicit barrier regions when they are enclosed in a parallel region

You can explicitly add cancellation points in your program using the omp cancellation point directive. When encountering implicit or explicit cancellation points, threads check whether cancellation for the innermost enclosing region of the specified type has been activated. If cancellation has been activated, cancellation is performed.

When an if expression is present in the omp cancel directive and the expression evaluates to false, the omp cancel does not activate cancellation, but the compiler still implicitly adds a cancellation point at the location of the omp cancel directive.

When cancellation is activated through omp cancel taskgroup, the cancellation of the tasks that belong to the taskgroup set of the innermost enclosing taskgroup region is performed as follows:

The task that encounters the omp cancel taskgroup directive continues execution till the end of its task region.
Any other task that has begun execution runs to its completion or until a cancellation point is reached. If a cancellation point is reached, the task continues execution till the end of its task region.
Any task that has not begun execution is discarded.

When cancellation is activated through omp cancel parallel, the cancellation of the threads that belong to the binding thread set is performed as follows:

The encountering thread continues execution till the end of the binding region.
Any other thread continues execution till the end of the parallel region or until a cancellation point is reached. If a cancellation point is reached, the thread continues execution till the end of the canceled region.
Any task and its descendent task that are created inside the parallel region by the omp task directive are canceled according to the taskgroup cancellation semantics.

When cancellation is activated through omp cancel sections or omp cancel for, the cancellation of the threads that belong to the binding thread set is performed as follows:

The encountering thread continues execution till the end of the binding region.
Any other thread continues execution till the end of the sections or loop region if no cancellation point is reached, or continues execution till the end of the canceled region if a cancellation point is reached.
Any task that is created inside the sections or loop region is not terminated.

If a task encounters a cancellation point of taskgroup, the task checks for all of the taskgroup sets to which the task belongs. If the cancellation of any of the taskgroup sets has been activated through omp cancel taskgroup, the task continues till the end of the task region.

If a thread encounters a cancellation point of parallel, sections, or for, the thread continues execution till the end of the canceled region if cancellation has been activated for the innermost enclosing region through omp cancel parallel, omp cancel sections, or omp cancel for.

When cancellation is activated through omp cancel parallel, the threads that encounter a barrier that is enclosed in a parallel region might exit the barrier and proceed to the end of the canceled region even if some threads in the team have not reached the barrier.

C++ only If the lifetime of an object ends at the end of the binding region, the object is destroyed when the cancellation is performed.

Deadlocks might arise during cancellation. To avoid this issue, take the following actions:

Release locks and other synchronization data structures that might cause a deadlock when cancellation is performed but blocked threads cannot be canceled.
Ensure proper synchronizations to avoid deadlocks that might arise from the cancellation of OpenMP regions that contain OpenMP synchronization constructs.

Notes:

If the cancellation of a region and the cancellation of its nested regions are performed at the same time, the behavior is undefined.
If one thread activates cancellation and another thread encounters a cancellation point at the same time, the order of the executions is undetermined.
If the construct that is canceled contains a reduction or lastprivate clause, the final value of the reduction or lastprivate variable is undefined.

Rules

Consider the following location restrictions of the omp cancel directive:

The omp cancel taskgroup directive must be nested inside a omp task directive, and the cancel region must be nested inside a taskgroup region.
The omp cancel sections directive must be nested inside a omp section or omp sections directive.
The omp cancel parallel directive must be nested inside a omp parallel directive.
The omp cancel for directive must be nested inside a omp for directive.

A worksharing construct that is canceled cannot have a nowait clause.

A loop construct that is canceled cannot have an ordered clause.

During the execution of a construct that is to be canceled, the cancellation point that the thread encounters must be within the construct.

Examples

In the following example, two levels of search are involved and each thread searches a slice of data structure. If the first level search is not successful, the second level search is performed. If one of the first level searches is successful, all other searches are terminated. The parallel region can be canceled using the omp cancel parallel and omp cancellation point parallel directives.

#include <omp.h>
void parallel_search () {
   #pragma omp parallel
   {
      int nthd=omp_get_thread_num();
      
      //check whether cancellation has been activated before proceed
      #pragma omp cancellation point parallel
      _Bool found = first_level_search(data[nthd]);
    
      if(found){
         //cancel the parallel construct
         #pragma omp cancel parallel
      }

      //check whether cancellation has been activated before proceed
      #pragma omp cancellation point parallel

      //If the first level search is not successful, go on to the second level search
      second_level_search(data[nthd]); 
   }
}

Voice your opinion on getting help information

Ask IBM compiler experts a technical question in the IBM XL compilers forum