From 99d4c1b09bb902c59e9cdec56a09d3e7761b0d00 Mon Sep 17 00:00:00 2001 From: Arnaud Charlet Date: Fri, 28 Aug 2020 04:46:52 -0400 Subject: [PATCH] [Ada] Improve documentation of pragma Abort_Defer gcc/ada/ * doc/gnat_rm/implementation_defined_pragmas.rst: Improve documentation of pragma Abort_Defer. * gnat_rm.texi: Regenerate. --- .../gnat_rm/implementation_defined_pragmas.rst | 16 +++++++++++++++- gcc/ada/gnat_rm.texi | 16 +++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst index af313c1f0bb..a5aff66c47b 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @@ -37,7 +37,21 @@ This pragma must appear at the start of the statement sequence of a handled sequence of statements (right after the ``begin``). It has the effect of deferring aborts for the sequence of statements (but not for the declarations or handlers, if any, associated with this statement -sequence). +sequence). This can also be useful for adding a polling point in Ada code, +where asynchronous abort of tasks is checked when leaving the statement +sequence, and is lighter than, for example, using ``delay 0.0;``, since with +zero-cost exception handling, propagating exceptions (implicitly used to +implement task abort) cannot be done reliably in an asynchronous way. + +An example of usage would be: + +.. code-block:: ada + + -- Add a polling point to check for task aborts + + begin + pragma Abort_Defer; + end; .. _Pragma-Abstract_State: diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi index af8bd07da9d..d4016aaa223 100644 --- a/gcc/ada/gnat_rm.texi +++ b/gcc/ada/gnat_rm.texi @@ -1394,7 +1394,21 @@ This pragma must appear at the start of the statement sequence of a handled sequence of statements (right after the @code{begin}). It has the effect of deferring aborts for the sequence of statements (but not for the declarations or handlers, if any, associated with this statement -sequence). +sequence). This can also be useful for adding a polling point in Ada code, +where asynchronous abort of tasks is checked when leaving the statement +sequence, and is lighter than, for example, using @code{delay 0.0;}, since with +zero-cost exception handling, propagating exceptions (implicitly used to +implement task abort) cannot be done reliably in an asynchronous way. + +An example of usage would be: + +@example +-- Add a polling point to check for task aborts + +begin + pragma Abort_Defer; +end; +@end example @node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas @anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1c}@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d} -- 2.30.2