From patchwork Wed Nov 26 01:51:22 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Malcolm X-Patchwork-Id: 414955 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 01FF21401DA for ; Wed, 26 Nov 2014 12:43:59 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references; q=dns; s= default; b=iSZHHeqwt2EG3YrOqvZVNQpHcQtArfQumn+UQWb+lV5WBBLYE7vb8 Os6JsGxme+Vkc0zahtj0W3LyV0oKRRmMoqms7M4F63pqbcmKx1jevJU6yU6qlAbg JseaUa2gPUX0k/JnyKmWFNLZOKzDx/p+3myvxseV00FnCkW7E6ryoA= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:from :to:cc:subject:date:message-id:in-reply-to:references; s= default; bh=ZVjGaduCX3vU/oI37V7P1ocrVOY=; b=U3h02c9iYiCeInMkUfR/ +c/0FypVH/LbUQk/PkRKUGtyoJmLixUS1V9Q+Y29vXCRJql7g+I09H/vswMVJ5WN uSyXWlGYfpMwq5eocSQOCmU2Ea2g267PoYiJBfa5fLJINC9BfjAmSX+8okwhlLZM dBhF//6uSS7AwbWeLD9pywM= Received: (qmail 17816 invoked by alias); 26 Nov 2014 01:43:50 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@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-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-User: qpsmtpd, 2 recipients X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-GCM-SHA384 encrypted) ESMTPS; Wed, 26 Nov 2014 01:43:43 +0000 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id sAQ1hgWq020177 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 25 Nov 2014 20:43:42 -0500 Received: from c64.redhat.com (vpn-239-49.phx2.redhat.com [10.3.239.49]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id sAQ1hdpO032335; Tue, 25 Nov 2014 20:43:41 -0500 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: Tue, 25 Nov 2014 20:51:22 -0500 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-IsSubscribed: yes 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.