HOME
| OPENMP API Specification: Version 5.0 November 2018

2.18.1  cancel Construct

SummaryThe cancel construct activates cancellation of the innermost enclosing region of the type specified. The cancel construct is a stand-alone directive.

Syntax

SVG-Viewer needed.

The syntax of the cancel construct is as follows:  

 
#pragma omp cancel construct-type-clause [ [,] if-clause] new-line  

where construct-type-clause is one of the following:  

 
parallel 
sections 
for 
taskgroup  

and if-clause is  

 
if ([ cancel :] scalar-expression)  

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the cancel construct is as follows:  

 
!$omp cancel construct-type-clause [ [,] if-clause]  

where construct-type-clause is one of the following:  

 
parallel 
sections 
do 
taskgroup  

and if-clause is  

 
if ([ cancel :] scalar-logical-expression)  

SVG-Viewer needed.

BindingThe binding thread set of the cancel region is the current team. The binding region of the cancel region is the innermost enclosing region of the type corresponding to the construct-type-clause specified in the directive (that is, the innermost parallel, sections, worksharing-loop, or taskgroup region).

DescriptionThe cancel construct activates cancellation of the binding region only if the cancel-var ICV is true, in which case the cancel construct causes the encountering task to continue execution at the end of the binding region if construct-type-clause is parallel, for, do, or sections. If the cancel-var ICV is true and construct-type-clause is taskgroup, the encountering task continues execution at the end of the current task region. If the cancel-var ICV is false, the cancel construct is ignored. Threads check for active cancellation only at cancellation points that are implied at the following locations:

When a thread reaches one of the above cancellation points and if the cancel-var ICV is true, then:

SVG-Viewer needed.

Note – If one thread activates cancellation and another thread encounters a cancellation point, the order of execution between the two threads is non-deterministic. Whether the thread that encounters a cancellation point detects the activated cancellation depends on the underlying hardware and operating system.

SVG-Viewer needed.

When cancellation of tasks is activated through a cancel construct with the taskgroup construct-type-clause, the tasks that belong to the taskgroup set of the innermost enclosing taskgroup region will be canceled. The task that encountered that construct continues execution at the end of its task region, which implies completion of that task. Any task that belongs to the innermost enclosing taskgroup and has already begun execution must run to completion or until a cancellation point is reached. Upon reaching a cancellation point and if cancellation is active, the task continues execution at the end of its task region, which implies the task’s completion. Any task that belongs to the innermost enclosing taskgroup and that has not begun execution may be discarded, which implies its completion.

When cancellation is active for a parallel, sections, or worksharing-loop region, each thread of the binding thread set resumes execution at the end of the canceled region if a cancellation point is encountered. If the canceled region is a parallel region, any tasks that have been created by a task or a taskloop construct and their descendent tasks are canceled according to the above taskgroup cancellation semantics. If the canceled region is a sections, or worksharing-loop region, no task cancellation occurs.

SVG-Viewer needed.

The usual C++ rules for object destruction are followed when cancellation is performed.

SVG-Viewer needed.

SVG-Viewer needed.

All private objects or subobjects with ALLOCATABLE attribute that are allocated inside the canceled construct are deallocated.

SVG-Viewer needed.

If the canceled construct contains a reduction, task_reduction or lastprivate clause, the final value of the list items that appeared in those clauses are undefined.

When an if clause is present on a cancel construct and the if expression evaluates to false, the cancel construct does not activate cancellation. The cancellation point associated with the cancel construct is always encountered regardless of the value of the if expression.

SVG-Viewer needed.

Note – The programmer is responsible for releasing locks and other synchronization data structures that might cause a deadlock when a cancel construct is encountered and blocked threads cannot be canceled. The programmer is also responsible for ensuring proper synchronizations to avoid deadlocks that might arise from cancellation of OpenMP regions that contain OpenMP synchronization constructs.

SVG-Viewer needed.

Execution Model Events If a task encounters a cancel construct that will activate cancellation then a cancel event occurs.

A discarded-task event occurs for any discarded tasks.

Tool Callbacks A thread dispatches a registered ompt_callback_cancel callback for each occurrence of a cancel event in the context of the encountering task. This callback has type signature ompt_callback_cancel_t; (flags & ompt_cancel_activated) always evaluates to true in the dispatched callback; (flags & ompt_cancel_parallel) evaluates to true in the dispatched callback if construct-type-clause is parallel; (flags & ompt_cancel_sections) evaluates to true in the dispatched callback if construct-type-clause is sections; (flags & ompt_cancel_loop) evaluates to true in the dispatched callback if construct-type-clause is for or do; and (flags & ompt_cancel_taskgroup) evaluates to true in the dispatched callback if construct-type-clause is taskgroup.

A thread dispatches a registered ompt_callback_cancel callback with the ompt_data_t associated with the discarded task as its task_data argument and ompt_cancel_discarded_task as its flags argument for each occurrence of a discarded-task event. The callback occurs in the context of the task that discards the task and has type signature ompt_callback_cancel_t.

RestrictionsThe restrictions to the cancel construct are as follows:

Cross References