[PATCH 01/02] PR jit/64018: Add description of error-handling to the JIT tutorial

[David Malcolm <dmalcolm at redhat dot com>]

gcc/jit/ChangeLog:
	PR jit/64018
	* docs/intro/tutorial02.rst: Spell out lifetime of generated code.
	Add description of error-handling, taken in part from...
	* docs/topics/contexts.rst (Error-handling): Expand, and move some
	content to tutorial02.rst.
---
 gcc/jit/docs/intro/tutorial02.rst | 38 ++++++++++++++++++++++++++++++++++++++
 gcc/jit/docs/topics/contexts.rst  | 22 +++++++++++++++++-----
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/gcc/jit/docs/intro/tutorial02.rst b/gcc/jit/docs/intro/tutorial02.rst
index f52499e..b484a9a 100644
--- a/gcc/jit/docs/intro/tutorial02.rst
+++ b/gcc/jit/docs/intro/tutorial02.rst
@@ -218,6 +218,44 @@ then call it:
 
   result: 25
 
+Once we're done with the code, we can release the result:
+
+.. code-block:: c
+
+   gcc_jit_result_release (result);
+
+We can't call ``square`` anymore once we've released ``result``.
+
+
+Error-handling
+**************
+Various kinds of errors are possible when using the API, such as
+mismatched types in an assignment.  You can only compile and get code
+from a context if no errors occur.
+
+Errors are printed on stderr; they typically contain the name of the API
+entrypoint where the error occurred, and pertinent information on the
+problem:
+
+.. code-block:: console
+
+  ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
+
+The API is designed to cope with errors without crashing, so you can get
+away with having a single error-handling check in your code:
+
+.. code-block:: c
+
+   void *fn_ptr = gcc_jit_result_get_code (result, "square");
+   if (!fn_ptr)
+     {
+       fprintf (stderr, "NULL fn_ptr");
+       goto error;
+     }
+
+For more information, see the :ref:`error-handling guide <error-handling>`
+within the Topic eference.
+
 
 Options
 *******
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index d8dd4f8..c3f8c52 100644
--- a/gcc/jit/docs/topics/contexts.rst
+++ b/gcc/jit/docs/topics/contexts.rst
@@ -101,18 +101,30 @@ within a process may use a given "family tree" of such contexts at once,
 and if you're using multiple threads you should provide your own locking
 around entire such context partitions.
 
+.. _error-handling:
 
 Error-handling
 --------------
-You can only compile and get code from a context if no errors occur.
-
-In general, if an error occurs when using an API entrypoint, it returns
-NULL.  You don't have to check everywhere for NULL results, since the
-API gracefully handles a NULL being passed in for any argument.
+Various kinds of errors are possible when using the API, such as
+mismatched types in an assignment.  You can only compile and get code from
+a context if no errors occur.
 
 Errors are printed on stderr and can be queried using
 :c:func:`gcc_jit_context_get_first_error`.
 
+They typically contain the name of the API entrypoint where the error
+occurred, and pertinent information on the problem:
+
+.. code-block:: console
+
+  ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
+
+In general, if an error occurs when using an API entrypoint, the
+entrypoint returns NULL.  You don't have to check everywhere for NULL
+results, since the API handles a NULL being passed in for any
+argument by issuing another error.  This typically leads to a cascade of
+followup error messages, but is safe (albeit verbose).
+
 .. function:: const char *\
               gcc_jit_context_get_first_error (gcc_jit_context *ctxt)
 
-- 
1.8.5.3