* [PATCH 02/02] Improvements to documentation of gcc_jit_context_release
2014-01-01 0:00 [PATCH 00/02] Improvements to jit documentation David Malcolm
@ 2014-01-01 0:00 ` David Malcolm
2014-01-01 0:00 ` [PATCH 01/02] PR jit/64018: Add description of error-handling to the JIT tutorial David Malcolm
1 sibling, 0 replies; 3+ messages in thread
From: David Malcolm @ 2014-01-01 0:00 UTC (permalink / raw)
To: gcc-patches, jit; +Cc: David Malcolm
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.
---
gcc/jit/docs/examples/tut02-square.c | 10 +++++++--
gcc/jit/docs/intro/tutorial02.rst | 6 ++++++
gcc/jit/docs/topics/functions.rst | 4 ++++
gcc/jit/docs/topics/results.rst | 39 ++++++++++++++++++++++++++++++++----
4 files changed, 53 insertions(+), 6 deletions(-)
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.
--
1.8.5.3
^ permalink raw reply [flat|nested] 3+ messages in thread* [PATCH 01/02] PR jit/64018: Add description of error-handling to the JIT tutorial
2014-01-01 0:00 [PATCH 00/02] Improvements to jit documentation David Malcolm
2014-01-01 0:00 ` [PATCH 02/02] Improvements to documentation of gcc_jit_context_release David Malcolm
@ 2014-01-01 0:00 ` David Malcolm
1 sibling, 0 replies; 3+ messages in thread
From: David Malcolm @ 2014-01-01 0:00 UTC (permalink / raw)
To: gcc-patches, jit; +Cc: David Malcolm
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
^ permalink raw reply [flat|nested] 3+ messages in thread