+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
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.
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)
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;
@}
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)
@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)
@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)
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.
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)
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;
}
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.
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
.. 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)
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\
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.
projects / gcc.git / commitdiff