16.1  cancel Construct

Clauses

Additional information

Binding

Semantics

Threads check for active cancellation only at cancellation points that are implied at the following locations:

• cancel regions;
• cancellation point regions;
• barrier regions;
• at the end of a worksharing-loop construct with a nowait clause and for which the same list item appears in both firstprivate and lastprivate clauses; and
• implicit barrier regions.

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

• If the thread is at a cancel or cancellation point region and cancel-directive-name is not taskgroup, the thread continues execution at the end of the canceled region if cancellation has been activated for the innermost enclosing region of the type specified.
• If the thread is at a cancel or cancellation point region and cancel-directive-name is taskgroup, the encountering task checks for active cancellation of all of the taskgroup sets to which the encountering task belongs, and continues execution at the end of the current task region if cancellation has been activated for any of the taskgroup sets.
• If the encountering task is at a barrier region or at the end of a worksharing-loop construct with a nowait clause and for which the same list item appears in both firstprivate and lastprivate clauses, the encountering task checks for active cancellation of the innermost enclosing parallel region. If cancellation has been activated, then the encountering task continues execution at the end of the canceled region.

When cancellation of tasks is activated through a cancel construct with taskgroup for cancel-directive-name, 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 completion of the task. Any task that belongs to the innermost enclosing taskgroup and that has not begun execution may be discarded, which implies its completion.

When cancellation of tasks is activated through a cancel construct with cancel-directive-name other than taskgroup, 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 not a parallel region, no task cancellation occurs.

If the canceled construct contains a reduction-scoping or lastprivate clause, the final values 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.

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 cancel-directive-name is parallel; (flags & ompt_cancel_sections) evaluates to true in the dispatched callback if cancel-directive-name is sections; (flags & ompt_cancel_loop) evaluates to true in the dispatched callback if cancel-directive-name is for or do; and (flags & ompt_cancel_taskgroup) evaluates to true in the dispatched callback if cancel-directive-name 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.

Restrictions

• The behavior for concurrent cancellation of a region and a region nested within it is unspecified.
• If cancel-directive-name is taskgroup, the cancel construct must be closely nested inside a task or a taskloop construct and the cancel region must be closely nested inside a taskgroup region.
• If cancel-directive-name is not taskgroup, the cancel construct must be closely nested inside an OpenMP construct that matches cancel-directive-name.
• A worksharing construct that is canceled must not have a nowait clause or a reduction clause with a user-defined reduction that uses omp_orig in the initializer-expr of the corresponding declare reduction directive.
• A worksharing-loop construct that is canceled must not have an ordered clause or a reduction clause with the inscan modifier.
• When cancellation is active for a parallel region, a thread in the team that binds to that region may not be executing or encounter a worksharing construct with an ordered clause, a reduction clause with the inscan modifier or a reduction clause with a user-defined reduction that uses omp_orig in the initializer-expr of the corresponding declare reduction directive.
• When cancellation is active for a parallel region, a thread in the team that binds to that region may not be executing or encounter a scope construct with a reduction clause with a user-defined reduction that uses omp_orig in the initializer-expr of the corresponding declare reduction directive.
• During execution of a construct that may be subject to cancellation, a thread must not encounter an orphaned cancellation point. That is, a cancellation point must only be encountered within that construct and must not be encountered elsewhere in its region.

Cross References

• omp_get_cancellation, see Section 18.2.8
• ompt_callback_cancel_t, see Section 19.5.2.18
• ompt_cancel_flag_t, see Section 19.4.4.26
• barrier directive, see Section 15.3.1
• cancel-var ICV, see Section 2.1
• cancellation point directive, see Section 16.2
• declare reduction directive, see Section 5.5.11
• do directive, see Section 11.5.2
• firstprivate clause, see Section 5.4.4
• for directive, see Section 11.5.1
• if clause, see Section 3.4
• nowait clause, see Section 15.6
• ordered clause, see Section 4.4.4
• parallel directive, see Section 10.1
• private clause, see Section 5.4.3
• reduction clause, see Section 5.5.8
• sections directive, see Section 11.3
• task directive, see Section 12.5
• taskgroup directive, see Section 15.4