Improvements to documentation of gcc_jit_context_release

gcc/jit/ChangeLog:
	* docs/examples/tut02-square.c (main): Release the context
	earlier, to show that this is possible.  Update error-handling
	to avoid a double-release of the context, and to avoid
	releasing a NULL result.
	* docs/intro/tutorial02.rst: Discuss gcc_jit_context_release.
	* docs/topics/functions.rst (GCC_JIT_FUNCTION_EXPORTED): Emphasize
	* docs/topics/results.rst (gcc_jit_result): Mention that this
	controls the lifetimes of machine code functions.
	(gcc_jit_result_get_code): Spell out the requirements for this
	to succeed, and the lifetime of the result.
	(gcc_jit_result_release): Mention that this invalidates any code
	that was obtained from the result.
	* docs/_build/texinfo/libgccjit.texi: Regenerate.

From-SVN: r218245

6 files changed, 126 insertions, 12 deletions

diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog
index 7dd84f0..8a23735 100644
--- a/gcc/jit/ChangeLog
+++ b/gcc/jit/ChangeLog
@@ -1,5 +1,21 @@
 2014-12-01  David Malcolm  <dmalcolm@redhat.com>
 
+	* docs/examples/tut02-square.c (main): Release the context
+	earlier, to show that this is possible.  Update error-handling
+	to avoid a double-release of the context, and to avoid
+	releasing a NULL result.
+	* docs/intro/tutorial02.rst: Discuss gcc_jit_context_release.
+	* docs/topics/functions.rst (GCC_JIT_FUNCTION_EXPORTED): Emphasize
+	* docs/topics/results.rst (gcc_jit_result): Mention that this
+	controls the lifetimes of machine code functions.
+	(gcc_jit_result_get_code): Spell out the requirements for this
+	to succeed, and the lifetime of the result.
+	(gcc_jit_result_release): Mention that this invalidates any code
+	that was obtained from the result.
+	* docs/_build/texinfo/libgccjit.texi: Regenerate.
+
+2014-12-01  David Malcolm  <dmalcolm@redhat.com>
+
 	PR jit/64018
 	* docs/intro/tutorial02.rst: Spell out lifetime of generated code.
 	Add description of error-handling, taken in part from...
diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi
index 641b556..f2e1e63 100644
--- a/gcc/jit/docs/_build/texinfo/libgccjit.texi
+++ b/gcc/jit/docs/_build/texinfo/libgccjit.texi
@@ -630,6 +630,14 @@ result = gcc_jit_context_compile (ctxt);
 
 and get a @pxref{16,,gcc_jit_result *}.
 
+At this point we're done with the context; we can release it:
+
+@example
+gcc_jit_context_release (ctxt);
+@end example
+
+@noindent
+
 We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific
 machine code routine within the result, in this case, the function we
 created above.
@@ -935,6 +943,10 @@ main (int argc, char **argv)
       goto error;
     @}
 
+  /* We're done with the context; we can release it: */
+  gcc_jit_context_release (ctxt);
+  ctxt = NULL;
+
   /* Extract the generated code from "result".  */
   void *fn_ptr = gcc_jit_result_get_code (result, "square");
   if (!fn_ptr)
@@ -948,8 +960,10 @@ main (int argc, char **argv)
   printf ("result: %d", square (5));
 
  error:
-  gcc_jit_context_release (ctxt);
-  gcc_jit_result_release (result);
+  if (ctxt)
+    gcc_jit_context_release (ctxt);
+  if (result)
+    gcc_jit_result_release (result);
   return 0;
 @}
 
@@ -5877,6 +5891,10 @@ values:
 
 Function is defined by the client code and visible
 by name outside of the JIT.
+
+This value is required if you want to extract machine code
+for this function from a @pxref{16,,gcc_jit_result} via
+@pxref{17,,gcc_jit_result_get_code()}.
 @end deffn
 
 @geindex GCC_JIT_FUNCTION_INTERNAL (C macro)
@@ -6251,7 +6269,9 @@ file, giving you @emph{something} you can step through in the debugger.
 @anchor{topics/results gcc_jit_result}@anchor{16}
 @deffn {C Type} gcc_jit_result
 
-A @cite{gcc_jit_result} encapsulates the result of compiling a context.
+A @cite{gcc_jit_result} encapsulates the result of compiling a context,
+and the lifetimes of any machine code functions that are
+returned.
 @end deffn
 
 @geindex gcc_jit_context_compile (C function)
@@ -6267,8 +6287,38 @@ This calls into GCC and builds the code, returning a
 @deffn {C Function} void *           gcc_jit_result_get_code (gcc_jit_result@w{ }*result, const char@w{ }*funcname)
 
 Locate a given function within the built machine code.
-This will need to be cast to a function pointer of the
-correct type before it can be called.
+
+Functions are looked up by name.  For this to succeed, a function
+with a name matching @cite{funcname} must have been created on
+@cite{result}'s context (or a parent context) via a call to
+@pxref{11,,gcc_jit_context_new_function()} with @cite{kind}
+@pxref{ac,,GCC_JIT_FUNCTION_EXPORTED}:
+
+@example
+gcc_jit_context_new_function (ctxt,
+                              any_location, /* or NULL */
+                              /* Required for func to be visible to
+                                 gcc_jit_result_get_code: */
+                              GCC_JIT_FUNCTION_EXPORTED,
+                              any_return_type,
+                              /* Must string-compare equal: */
+                              funcname,
+                              /* etc */);
+@end example
+
+@noindent
+
+If such a function is not found (or @cite{result} or @cite{funcname} are
+@code{NULL}), an error message will be emitted on stderr and
+@code{NULL} will be returned.
+
+If the function is found, the result will need to be cast to a
+function pointer of the correct type before it can be called.
+
+Note that the resulting machine code becomes invalid after
+@pxref{39,,gcc_jit_result_release()} is called on the
+@cite{gcc_jit_result *}; attempting to call it after that may lead
+to a segmentation fault.
 @end deffn
 
 @geindex gcc_jit_result_release (C function)
@@ -6277,7 +6327,8 @@ correct type before it can be called.
 
 Once we're done with the code, this unloads the built .so file.
 This cleans up the result; after calling this, it's no longer
-valid to use the result.
+valid to use the result, or any code that was obtained by calling
+@pxref{17,,gcc_jit_result_get_code()} on it.
 @end deffn
 
 @c Copyright (C) 2014 Free Software Foundation, Inc.
diff --git a/gcc/jit/docs/examples/tut02-square.c b/gcc/jit/docs/examples/tut02-square.c
index 5eae179..fea3f11 100644
--- a/gcc/jit/docs/examples/tut02-square.c
+++ b/gcc/jit/docs/examples/tut02-square.c
@@ -88,6 +88,10 @@ main (int argc, char **argv)
       goto error;
     }
 
+  /* We're done with the context; we can release it: */
+  gcc_jit_context_release (ctxt);
+  ctxt = NULL;
+
   /* Extract the generated code from "result".  */
   void *fn_ptr = gcc_jit_result_get_code (result, "square");
   if (!fn_ptr)
@@ -101,7 +105,9 @@ main (int argc, char **argv)
   printf ("result: %d", square (5));
 
  error:
-  gcc_jit_context_release (ctxt);
-  gcc_jit_result_release (result);
+  if (ctxt)
+    gcc_jit_context_release (ctxt);
+  if (result)
+    gcc_jit_result_release (result);
   return 0;
 }
diff --git a/gcc/jit/docs/intro/tutorial02.rst b/gcc/jit/docs/intro/tutorial02.rst
index b484a9a..b8d35ae 100644
--- a/gcc/jit/docs/intro/tutorial02.rst
+++ b/gcc/jit/docs/intro/tutorial02.rst
@@ -192,6 +192,12 @@ OK, we've populated the context.  We can now compile it using
 
 and get a :c:type:`gcc_jit_result *`.
 
+At this point we're done with the context; we can release it:
+
+.. code-block:: c
+
+   gcc_jit_context_release (ctxt);
+
 We can now use :c:func:`gcc_jit_result_get_code` to look up a specific
 machine code routine within the result, in this case, the function we
 created above.
diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst
index aa0c069..1795b0c 100644
--- a/gcc/jit/docs/topics/functions.rst
+++ b/gcc/jit/docs/topics/functions.rst
@@ -84,6 +84,10 @@ Functions
          Function is defined by the client code and visible
          by name outside of the JIT.
 
+         This value is required if you want to extract machine code
+         for this function from a :type:`gcc_jit_result` via
+         :func:`gcc_jit_result_get_code`.
+
       .. macro::   GCC_JIT_FUNCTION_INTERNAL
 
          Function is defined by the client code, but is invisible
diff --git a/gcc/jit/docs/topics/results.rst b/gcc/jit/docs/topics/results.rst
index 10dc94f..9904495 100644
--- a/gcc/jit/docs/topics/results.rst
+++ b/gcc/jit/docs/topics/results.rst
@@ -22,7 +22,9 @@ Compilation results
 
 .. type:: gcc_jit_result
 
-  A `gcc_jit_result` encapsulates the result of compiling a context.
+  A `gcc_jit_result` encapsulates the result of compiling a context,
+  and the lifetimes of any machine code functions that are
+  returned.
 
 .. function:: gcc_jit_result *\
               gcc_jit_context_compile (gcc_jit_context *ctxt)
@@ -36,8 +38,36 @@ Compilation results
                                        const char *funcname)
 
    Locate a given function within the built machine code.
-   This will need to be cast to a function pointer of the
-   correct type before it can be called.
+
+   Functions are looked up by name.  For this to succeed, a function
+   with a name matching `funcname` must have been created on
+   `result`'s context (or a parent context) via a call to
+   :func:`gcc_jit_context_new_function` with `kind`
+   :macro:`GCC_JIT_FUNCTION_EXPORTED`:
+
+   .. code-block:: c
+
+     gcc_jit_context_new_function (ctxt,
+                                   any_location, /* or NULL */
+                                   /* Required for func to be visible to
+                                      gcc_jit_result_get_code: */
+                                   GCC_JIT_FUNCTION_EXPORTED,
+                                   any_return_type,
+                                   /* Must string-compare equal: */
+                                   funcname,
+                                   /* etc */);
+
+   If such a function is not found (or `result` or `funcname` are
+   ``NULL``), an error message will be emitted on stderr and
+   ``NULL`` will be returned.
+
+   If the function is found, the result will need to be cast to a
+   function pointer of the correct type before it can be called.
+
+   Note that the resulting machine code becomes invalid after
+   :func:`gcc_jit_result_release` is called on the
+   `gcc_jit_result *`; attempting to call it after that may lead
+   to a segmentation fault.
 
 
 .. function:: void\
@@ -45,4 +75,5 @@ Compilation results
 
    Once we're done with the code, this unloads the built .so file.
    This cleans up the result; after calling this, it's no longer
-   valid to use the result.
+   valid to use the result, or any code that was obtained by calling
+   :func:`gcc_jit_result_get_code` on it.