OpenE2K/gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

jit: clarify (lack of) lifetime requirements on input const char *

Browse Source 
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
This commit is contained in:
David Malcolm 2015-07-01 12:34:24 +00:00 committed by David Malcolm
parent 7946683835
commit c575221ada
7 changed files with 144 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
gcc/jit/ChangeLog
View File

@ -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

69
gcc/jit/docs/_build/texinfo/libgccjit.texi vendored
View File

@ -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

4
gcc/jit/docs/topics/contexts.rst
View File

@ -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

7
gcc/jit/docs/topics/expressions.rst
View File

@ -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`:

34
gcc/jit/docs/topics/functions.rst
View File

@ -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,\

4
gcc/jit/docs/topics/locations.rst
View File

@ -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

12
gcc/jit/docs/topics/types.rst
View File

@ -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)