[Ada] Improve documentation of pragma Abort_Defer
authorArnaud Charlet <charlet@adacore.com>
Fri, 28 Aug 2020 08:46:52 +0000 (04:46 -0400)
committerPierre-Marie de Rodat <derodat@adacore.com>
Fri, 23 Oct 2020 08:24:53 +0000 (04:24 -0400)
gcc/ada/

* doc/gnat_rm/implementation_defined_pragmas.rst: Improve
documentation of pragma Abort_Defer.
* gnat_rm.texi: Regenerate.

gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst
gcc/ada/gnat_rm.texi

index af313c1f0bb630f34af9d1e27383e431f1bc85be..a5aff66c47b60a0c95e8402619247805fa924a58 100644 (file)
@@ -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:
 
index af8bd07da9d23762a382afc7426850265884cbea..d4016aaa223be6c895af4065cdaae3baa52e5c9f 100644 (file)
@@ -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}