This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[PATCH, committed] jit: clarify (lack of) lifetime requirements on input const char *
- From: David Malcolm <dmalcolm at redhat dot com>
- To: jit at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Cc: David Malcolm <dmalcolm at redhat dot com>
- Date: Wed, 1 Jul 2015 08:48:22 -0400
- Subject: [PATCH, committed] jit: clarify (lack of) lifetime requirements on input const char *
- Authentication-results: sourceware.org; auth=none
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)
--
1.8.5.3