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.

From-SVN: r225245

7 files changed, 144 insertions, 3 deletions

diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog
index 325f3b8..469d1bc 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 212df10..f6ab632 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 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)