From: David Malcolm Date: Mon, 1 Dec 2014 18:53:44 +0000 (+0000) Subject: Improvements to documentation of gcc_jit_context_release X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=81ba15f10524cc46bf2afbe4fc07f783315c6d94;p=gcc.git 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 --- diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog index 7dd84f08e17..8a2373582e6 100644 --- a/gcc/jit/ChangeLog +++ b/gcc/jit/ChangeLog @@ -1,3 +1,19 @@ +2014-12-01 David Malcolm + + * 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 PR jit/64018 diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi index 641b556e069..f2e1e636e11 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 5eae1799949..fea3f1104d5 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 b484a9a7311..b8d35ae822d 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 aa0c0694182..1795b0c221a 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 10dc94f2cec..99044959a21 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.