From: David Malcolm Date: Wed, 1 Jul 2015 12:34:24 +0000 (+0000) Subject: jit: clarify (lack of) lifetime requirements on input const char * X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=c575221adaa3075be660a28371977f52ce939ba8;p=gcc.git 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 --- 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 + + * 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 * 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)