summaryrefslogtreecommitdiff
path: root/gcc/jit
diff options
context:
space:
mode:
authordmalcolm <dmalcolm@138bc75d-0d04-0410-961f-82ee72b054a4>2015-07-01 12:34:24 +0000
committerdmalcolm <dmalcolm@138bc75d-0d04-0410-961f-82ee72b054a4>2015-07-01 12:34:24 +0000
commit1fa42b0566972abc668f3aa88e5534092af99c2c (patch)
treebcf2f6e8f13471582397d75105c3321cc4d570aa /gcc/jit
parentbdccabb2604c4a2f714cea5846ad8526cd2eb496 (diff)
downloadgcc-1fa42b0566972abc668f3aa88e5534092af99c2c.tar.gz
jit: clarify (lack of) lifetime requirements on input const char *
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. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@225245 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'gcc/jit')
-rw-r--r--gcc/jit/ChangeLog17
-rw-r--r--gcc/jit/docs/_build/texinfo/libgccjit.texi69
-rw-r--r--gcc/jit/docs/topics/contexts.rst4
-rw-r--r--gcc/jit/docs/topics/expressions.rst7
-rw-r--r--gcc/jit/docs/topics/functions.rst34
-rw-r--r--gcc/jit/docs/topics/locations.rst4
-rw-r--r--gcc/jit/docs/topics/types.rst12
7 files changed, 144 insertions, 3 deletions
diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog
index 325f3b8883f..469d1bc2dab 100644
--- a/gcc/jit/ChangeLog
+++ b/gcc/jit/ChangeLog
@@ -1,3 +1,20 @@
+2015-07-01 David Malcolm <dmalcolm@redhat.com>
+
+ * 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.
+
2015-06-30 David Malcolm <dmalcolm@redhat.com>
* docs/cp/topics/functions.rst (Blocks): Add switch statements to
diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi
index 212df10ff05..f6ab632688d 100644
--- a/gcc/jit/docs/_build/texinfo/libgccjit.texi
+++ b/gcc/jit/docs/_build/texinfo/libgccjit.texi
@@ -19,7 +19,7 @@
@copying
@quotation
-libgccjit 6.0.0 (experimental 20150630), June 30, 2015
+libgccjit 6.0.0 (experimental 20150701), July 01, 2015
David Malcolm
@@ -5287,6 +5287,10 @@ Set a string option of the context.
@deffn {C Type} enum gcc_jit_str_option
@end deffn
+The parameter @code{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:
@geindex GCC_JIT_STR_OPTION_PROGNAME (C macro)
@@ -6077,6 +6081,10 @@ gcc_jit_struct_set_fields (node, NULL, 2, fields);
@deffn {C Function} gcc_jit_field * gcc_jit_context_new_field (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name)
Construct a new field, with the given type and name.
+
+The parameter @code{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.
@end deffn
@geindex gcc_jit_field_as_object (C function)
@@ -6093,6 +6101,10 @@ Upcast from field to object.
@quotation
Construct a new struct type, with the given name and fields.
+
+The parameter @code{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.
@end quotation
@end deffn
@@ -6104,6 +6116,10 @@ Construct a new struct type, with the given name, but without
specifying the fields. The fields can be omitted (in which case the
size of the struct is not known), or later specified using
@pxref{85,,gcc_jit_struct_set_fields()}.
+
+The parameter @code{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.
@end deffn
@geindex gcc_jit_struct_as_type (C function)
@@ -6327,6 +6343,10 @@ gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
Generate an rvalue for the given NIL-terminated string, of type
@code{GCC_JIT_TYPE_CONST_CHAR_PTR}.
+
+The parameter @code{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.
@end deffn
@node Unary Operations,Binary Operations,Simple expressions,Rvalues
@@ -6975,6 +6995,10 @@ in C.
Add a new global variable of the given type and name to the context.
+The parameter @code{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 @pxref{16,,gcc_jit_result}:
@@ -7150,6 +7174,10 @@ A @cite{gcc_jit_param} represents a parameter to a function.
In preparation for creating a function, create a new parameter of the
given type and name.
+
+The parameter @code{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.
@end deffn
Parameters are lvalues, and thus are also rvalues (and objects), so the
@@ -7249,6 +7277,10 @@ above 0; when optimization is off, this is essentially the
same as GCC_JIT_FUNCTION_INTERNAL.
@end deffn
@end quotation
+
+The parameter @code{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.
@end deffn
@geindex gcc_jit_context_get_builtin_function (C function)
@@ -7283,6 +7315,10 @@ Emit the function in graphviz format to the given path.
Create a new local variable within the function, of the given type and
name.
+
+The parameter @code{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.
@end deffn
@node Blocks,Statements,Functions,Creating and using functions
@@ -7316,7 +7352,19 @@ one function.
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.:
+
+@example
+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);
+ @}
+@end example
+
+@noindent
@end deffn
@geindex gcc_jit_block_as_object (C function)
@@ -7411,6 +7459,19 @@ seen via @pxref{66,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE},
and thus may be of use when debugging how your project's internal
representation gets converted to the libgccjit IR.
+
+The parameter @code{text} must be non-NULL. It is copied, so the input
+buffer does not need to outlive the call. For example:
+
+@example
+char buf[100];
+snprintf (buf, sizeof (buf),
+ "op%i: %s",
+ pc, opcode_names[op->op_opcode]);
+gcc_jit_block_add_comment (block, loc, buf);
+@end example
+
+@noindent
@end deffn
@geindex gcc_jit_block_end_with_conditional (C function)
@@ -7747,6 +7808,10 @@ gcc_jit_context_set_bool_option (
Create a @cite{gcc_jit_location} instance representing the given source
location.
+
+The parameter @code{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.
@end deffn
@menu
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index 1dd4685a4c8..78bcb71fac4 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 621991fcc70..c12a3780a9e 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 94db471615c..f2f8f34970e 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 58a76b675fc..e5e92738683 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 fa7aea677c1..5bfba726c00 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)