[gcc r11-4299] [Ada] Improve documentation of pragma Abort_Defer
Pierre-Marie de Rodat
pmderodat@gcc.gnu.org
Fri Oct 23 08:27:51 GMT 2020
https://gcc.gnu.org/g:99d4c1b09bb902c59e9cdec56a09d3e7761b0d00
commit r11-4299-g99d4c1b09bb902c59e9cdec56a09d3e7761b0d00
Author: Arnaud Charlet <charlet@adacore.com>
Date: Fri Aug 28 04:46:52 2020 -0400
[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.
Diff:
---
gcc/ada/doc/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}
More information about the Gcc-cvs
mailing list