From patchwork Wed Jul 1 12:48:22 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: David Malcolm X-Patchwork-Id: 490120 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 A5C6F1402AD for ; Wed, 1 Jul 2015 22:35:12 +1000 (AEST) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b=tzh+VsSJ; dkim-atps=neutral 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; q=dns; s=default; b=LA5TjwPLeHN0 Cal9vJB/nEfbTt6soWS9SeVUEf3GzNnUC/URXEnJ4csorCwWlJLYzJf91rysJKqo 35SJ/nXlzB7Uw8TnFnZktUr3oXSbc5BYAeef9/4UifpwxEX314EiRs9bxre+p4+8 BABbN3KdNeuLoSSlVpaf7KMlCU/X4hA= 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; s=default; bh=M0X+lbix0txxe0YxNW 6LozGWgyQ=; b=tzh+VsSJ9khPKo79hS3UMa6eB1xemZmLc4Ual3YxnwCCkKPOtR It6Zwkip3iSLBm5xOt4ZWWJ+AzOLh8Sqb182If0bkJUlAvpp5njEmNVYvlSBBl2t hCpfPgcpRTvdiDWSTrB9qCW3iViG3OxVaEvmwEkE6pPdKmVT+xXfWxQXw= Received: (qmail 84240 invoked by alias); 1 Jul 2015 12:35:05 -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 84216 invoked by uid 89); 1 Jul 2015 12:35:05 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.7 required=5.0 tests=AWL, BAYES_00, KAM_LAZY_DOMAIN_SECURITY, RP_MATCHES_RCVD, SPF_HELO_PASS autolearn=no 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, 01 Jul 2015 12:35:03 +0000 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by mx1.redhat.com (Postfix) with ESMTPS id 97B942CD859; Wed, 1 Jul 2015 12:35:02 +0000 (UTC) Received: from c64.redhat.com (vpn-232-60.phx2.redhat.com [10.3.232.60]) by int-mx10.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id t61CZ1BC008463; Wed, 1 Jul 2015 08:35:02 -0400 From: David Malcolm To: jit@gcc.gnu.org, gcc-patches@gcc.gnu.org Cc: David Malcolm Subject: [PATCH, committed] jit: clarify (lack of) lifetime requirements on input const char * Date: Wed, 1 Jul 2015 08:48:22 -0400 Message-Id: <1435754902-33000-1-git-send-email-dmalcolm@redhat.com> X-IsSubscribed: yes Committed to trunk as r225245. gcc/jit/ChangeLog: * docs/topics/contexts.rst (gcc_jit_context_set_bool_option): Clarify lack of lifetime requirements on (const char *) parameter. * docs/topics/expressions.rst (gcc_jit_context_new_string_literal): Likewise. (gcc_jit_context_new_global): Likewise. * docs/topics/functions.rst (gcc_jit_context_new_param): Likewise. (gcc_jit_context_new_function): Likewise. (gcc_jit_function_new_block): Likewise. (gcc_jit_block_add_comment): Likewise. * docs/topics/locations.rst (gcc_jit_context_new_location): Likewise. * docs/topics/types.rst (gcc_jit_context_new_field): Likewise. (gcc_jit_context_new_struct_type): Likewise. * docs/_build/texinfo/libgccjit.texi: Regenerate. --- gcc/jit/docs/topics/contexts.rst | 4 ++++ gcc/jit/docs/topics/expressions.rst | 7 +++++++ gcc/jit/docs/topics/functions.rst | 34 +++++++++++++++++++++++++++++++++- gcc/jit/docs/topics/locations.rst | 4 ++++ gcc/jit/docs/topics/types.rst | 12 ++++++++++++ 5 files changed, 60 insertions(+), 1 deletion(-) diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst index 1dd4685..78bcb71 100644 --- a/gcc/jit/docs/topics/contexts.rst +++ b/gcc/jit/docs/topics/contexts.rst @@ -313,6 +313,10 @@ String Options .. type:: enum gcc_jit_str_option + The parameter ``value`` can be NULL. If non-NULL, the call takes a + copy of the underlying string, so it is valid to pass in a pointer to + an on-stack buffer. + There is just one string option specified this way: .. macro:: GCC_JIT_STR_OPTION_PROGNAME diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst index 621991f..c12a378 100644 --- a/gcc/jit/docs/topics/expressions.rst +++ b/gcc/jit/docs/topics/expressions.rst @@ -122,6 +122,9 @@ Simple expressions Generate an rvalue for the given NIL-terminated string, of type :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`. + The parameter ``value`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. Unary Operations **************** @@ -466,6 +469,10 @@ Global variables Add a new global variable of the given type and name to the context. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + The "kind" parameter determines the visibility of the "global" outside of the :c:type:`gcc_jit_result`: diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst index 94db471..f2f8f34 100644 --- a/gcc/jit/docs/topics/functions.rst +++ b/gcc/jit/docs/topics/functions.rst @@ -35,6 +35,10 @@ Params In preparation for creating a function, create a new parameter of the given type and name. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + Parameters are lvalues, and thus are also rvalues (and objects), so the following upcasts are available: @@ -111,6 +115,10 @@ Functions above 0; when optimization is off, this is essentially the same as GCC_JIT_FUNCTION_INTERNAL. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + .. function:: gcc_jit_function *\ gcc_jit_context_get_builtin_function (gcc_jit_context *ctxt,\ const char *name) @@ -140,6 +148,9 @@ Functions Create a new local variable within the function, of the given type and name. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. Blocks ------ @@ -166,7 +177,17 @@ Blocks Create a basic block of the given name. The name may be NULL, but providing meaningful names is often helpful when debugging: it may show up in dumps of the internal representation, and in error - messages. + messages. It is copied, so the input buffer does not need to outlive + the call; you can pass in a pointer to an on-stack buffer, e.g.: + + .. code-block:: c + + for (pc = 0; pc < fn->fn_num_ops; pc++) + { + char buf[16]; + sprintf (buf, "instr%i", pc); + state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf); + } .. function:: gcc_jit_object *\ gcc_jit_block_as_object (gcc_jit_block *block) @@ -252,6 +273,17 @@ Statements and thus may be of use when debugging how your project's internal representation gets converted to the libgccjit IR. + The parameter ``text`` must be non-NULL. It is copied, so the input + buffer does not need to outlive the call. For example: + + .. code-block:: c + + char buf[100]; + snprintf (buf, sizeof (buf), + "op%i: %s", + pc, opcode_names[op->op_opcode]); + gcc_jit_block_add_comment (block, loc, buf); + .. function:: void\ gcc_jit_block_end_with_conditional (gcc_jit_block *block,\ gcc_jit_location *loc,\ diff --git a/gcc/jit/docs/topics/locations.rst b/gcc/jit/docs/topics/locations.rst index 58a76b6..e5e9273 100644 --- a/gcc/jit/docs/topics/locations.rst +++ b/gcc/jit/docs/topics/locations.rst @@ -52,6 +52,10 @@ Source Locations Create a `gcc_jit_location` instance representing the given source location. + The parameter ``filename`` must be non-NULL. The call takes a copy of + the underlying string, so it is valid to pass in a pointer to an + on-stack buffer. + Faking it --------- If you don't have source code for your internal representation, but need diff --git a/gcc/jit/docs/topics/types.rst b/gcc/jit/docs/topics/types.rst index fa7aea6..5bfba72 100644 --- a/gcc/jit/docs/topics/types.rst +++ b/gcc/jit/docs/topics/types.rst @@ -180,6 +180,10 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and Construct a new field, with the given type and name. + The parameter ``name`` must be non-NULL. The call takes a copy of the + underlying string, so it is valid to pass in a pointer to an on-stack + buffer. + .. function:: gcc_jit_object *\ gcc_jit_field_as_object (gcc_jit_field *field) @@ -194,6 +198,10 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and Construct a new struct type, with the given name and fields. + The parameter ``name`` must be non-NULL. The call takes a copy of + the underlying string, so it is valid to pass in a pointer to an + on-stack buffer. + .. function:: gcc_jit_struct *\ gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\ gcc_jit_location *loc,\ @@ -204,6 +212,10 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and size of the struct is not known), or later specified using :c:func:`gcc_jit_struct_set_fields`. + The parameter ``name`` must be non-NULL. The call takes a copy of + the underlying string, so it is valid to pass in a pointer to an + on-stack buffer. + .. function:: gcc_jit_type *\ gcc_jit_struct_as_type (gcc_jit_struct *struct_type)