From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17817 invoked by alias); 26 Nov 2014 01:43:50 -0000 Mailing-List: contact jit-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Subscribe: Sender: jit-owner@gcc.gnu.org Received: (qmail 17774 invoked by uid 89); 26 Nov 2014 01:43:47 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Checked: by ClamAV 0.98.4 on sourceware.org X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.0 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-Spam-Status: No, score=-2.0 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on sourceware.org X-Spam-Level: X-Spam-User: qpsmtpd, 2 recipients X-HELO: mx1.redhat.com From: David Malcolm To: gcc-patches@gcc.gnu.org, jit@gcc.gnu.org Cc: David Malcolm Subject: [PATCH 02/02] Improvements to documentation of gcc_jit_context_release Date: Wed, 01 Jan 2014 00:00:00 -0000 Message-Id: <1416966682-15853-3-git-send-email-dmalcolm@redhat.com> In-Reply-To: <1416966682-15853-1-git-send-email-dmalcolm@redhat.com> References: <1416966682-15853-1-git-send-email-dmalcolm@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.22 X-SW-Source: 2014-q4/txt/msg00218.txt.bz2 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