| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Funding Free Software", the Front-Cover |
| Texts being (a) (see below), and with the Back-Cover Texts being (b) |
| (see below). A copy of the license is included in the section entitled |
| "GNU Free Documentation License". |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>GNU Compiler Collection (GCC) Internals: GTY Options</title> |
| |
| <meta name="description" content="GNU Compiler Collection (GCC) Internals: GTY Options"> |
| <meta name="keywords" content="GNU Compiler Collection (GCC) Internals: GTY Options"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="Type-Information.html#Type-Information" rel="up" title="Type Information"> |
| <link href="Inheritance-and-GTY.html#Inheritance-and-GTY" rel="next" title="Inheritance and GTY"> |
| <link href="Type-Information.html#Type-Information" rel="prev" title="Type Information"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="GTY-Options"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="Inheritance-and-GTY.html#Inheritance-and-GTY" accesskey="n" rel="next">Inheritance and GTY</a>, Up: <a href="Type-Information.html#Type-Information" accesskey="u" rel="up">Type Information</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <hr> |
| <a name="The-Inside-of-a-GTY_0028_0028_0029_0029"></a> |
| <h3 class="section">22.1 The Inside of a <code>GTY(())</code></h3> |
| |
| <p>Sometimes the C code is not enough to fully describe the type |
| structure. Extra information can be provided with <code>GTY</code> options |
| and additional markers. Some options take a parameter, which may be |
| either a string or a type name, depending on the parameter. If an |
| option takes no parameter, it is acceptable either to omit the |
| parameter entirely, or to provide an empty string as a parameter. For |
| example, <code>GTY ((skip))<!-- /@w --></code> and <code>GTY ((skip ("")))<!-- /@w --></code> are |
| equivalent. |
| </p> |
| <p>When the parameter is a string, often it is a fragment of C code. Four |
| special escapes may be used in these strings, to refer to pieces of |
| the data structure being marked: |
| </p> |
| <a name="index-_0025-in-GTY-option"></a> |
| <dl compact="compact"> |
| <dt><code>%h</code></dt> |
| <dd><p>The current structure. |
| </p></dd> |
| <dt><code>%1</code></dt> |
| <dd><p>The structure that immediately contains the current structure. |
| </p></dd> |
| <dt><code>%0</code></dt> |
| <dd><p>The outermost structure that contains the current structure. |
| </p></dd> |
| <dt><code>%a</code></dt> |
| <dd><p>A partial expression of the form <code>[i1][i2]…</code> that indexes |
| the array item currently being marked. |
| </p></dd> |
| </dl> |
| |
| <p>For instance, suppose that you have a structure of the form |
| </p><div class="smallexample"> |
| <pre class="smallexample">struct A { |
| … |
| }; |
| struct B { |
| struct A foo[12]; |
| }; |
| </pre></div> |
| <p>and <code>b</code> is a variable of type <code>struct B</code>. When marking |
| ‘<samp>b.foo[11]</samp>’, <code>%h</code> would expand to ‘<samp>b.foo[11]</samp>’, |
| <code>%0</code> and <code>%1</code> would both expand to ‘<samp>b</samp>’, and <code>%a</code> |
| would expand to ‘<samp>[11]</samp>’. |
| </p> |
| <p>As in ordinary C, adjacent strings will be concatenated; this is |
| helpful when you have a complicated expression. |
| </p><div class="smallexample"> |
| <pre class="smallexample">GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE" |
| " ? TYPE_NEXT_VARIANT (&%h.generic)" |
| " : TREE_CHAIN (&%h.generic)"))) |
| </pre></div> |
| |
| <p>The available options are: |
| </p> |
| <dl compact="compact"> |
| <dd><a name="index-length"></a> |
| </dd> |
| <dt><code>length ("<var>expression</var>")</code></dt> |
| <dd> |
| <p>There are two places the type machinery will need to be explicitly told |
| the length of an array of non-atomic objects. The first case is when a |
| structure ends in a variable-length array, like this: |
| </p><div class="smallexample"> |
| <pre class="smallexample">struct GTY(()) rtvec_def { |
| int num_elem; /* <span class="roman">number of elements</span> */ |
| rtx GTY ((length ("%h.num_elem"))) elem[1]; |
| }; |
| </pre></div> |
| |
| <p>In this case, the <code>length</code> option is used to override the specified |
| array length (which should usually be <code>1</code>). The parameter of the |
| option is a fragment of C code that calculates the length. |
| </p> |
| <p>The second case is when a structure or a global variable contains a |
| pointer to an array, like this: |
| </p><div class="smallexample"> |
| <pre class="smallexample">struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter; |
| </pre></div> |
| <p>In this case, <code>iter</code> has been allocated by writing something like |
| </p><div class="smallexample"> |
| <pre class="smallexample"> x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse); |
| </pre></div> |
| <p>and the <code>collapse</code> provides the length of the field. |
| </p> |
| <p>This second use of <code>length</code> also works on global variables, like: |
| </p><pre class="verbatim">static GTY((length("reg_known_value_size"))) rtx *reg_known_value; |
| </pre> |
| <p>Note that the <code>length</code> option is only meant for use with arrays of |
| non-atomic objects, that is, objects that contain pointers pointing to |
| other GTY-managed objects. For other GC-allocated arrays and strings |
| you should use <code>atomic</code>. |
| </p> |
| <a name="index-skip"></a> |
| </dd> |
| <dt><code>skip</code></dt> |
| <dd> |
| <p>If <code>skip</code> is applied to a field, the type machinery will ignore it. |
| This is somewhat dangerous; the only safe use is in a union when one |
| field really isn’t ever used. |
| </p> |
| <a name="index-desc"></a> |
| <a name="index-tag"></a> |
| <a name="index-default"></a> |
| </dd> |
| <dt><code>desc ("<var>expression</var>")</code></dt> |
| <dt><code>tag ("<var>constant</var>")</code></dt> |
| <dt><code>default</code></dt> |
| <dd> |
| <p>The type machinery needs to be told which field of a <code>union</code> is |
| currently active. This is done by giving each field a constant |
| <code>tag</code> value, and then specifying a discriminator using <code>desc</code>. |
| The value of the expression given by <code>desc</code> is compared against |
| each <code>tag</code> value, each of which should be different. If no |
| <code>tag</code> is matched, the field marked with <code>default</code> is used if |
| there is one, otherwise no field in the union will be marked. |
| </p> |
| <p>In the <code>desc</code> option, the “current structure” is the union that |
| it discriminates. Use <code>%1</code> to mean the structure containing it. |
| There are no escapes available to the <code>tag</code> option, since it is a |
| constant. |
| </p> |
| <p>For example, |
| </p><div class="smallexample"> |
| <pre class="smallexample">struct GTY(()) tree_binding |
| { |
| struct tree_common common; |
| union tree_binding_u { |
| tree GTY ((tag ("0"))) scope; |
| struct cp_binding_level * GTY ((tag ("1"))) level; |
| } GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope; |
| tree value; |
| }; |
| </pre></div> |
| |
| <p>In this example, the value of BINDING_HAS_LEVEL_P when applied to a |
| <code>struct tree_binding *</code> is presumed to be 0 or 1. If 1, the type |
| mechanism will treat the field <code>level</code> as being present and if 0, |
| will treat the field <code>scope</code> as being present. |
| </p> |
| <p>The <code>desc</code> and <code>tag</code> options can also be used for inheritance |
| to denote which subclass an instance is. See <a href="Inheritance-and-GTY.html#Inheritance-and-GTY">Inheritance and GTY</a> |
| for more information. |
| </p> |
| <a name="index-param_005fis"></a> |
| <a name="index-use_005fparam"></a> |
| </dd> |
| <dt><code>param_is (<var>type</var>)</code></dt> |
| <dt><code>use_param</code></dt> |
| <dd> |
| <p>Sometimes it’s convenient to define some data structure to work on |
| generic pointers (that is, <code>PTR</code>) and then use it with a specific |
| type. <code>param_is</code> specifies the real type pointed to, and |
| <code>use_param</code> says where in the generic data structure that type |
| should be put. |
| </p> |
| <p>For instance, to have a <code>htab_t</code> that points to trees, one would |
| write the definition of <code>htab_t</code> like this: |
| </p><div class="smallexample"> |
| <pre class="smallexample">typedef struct GTY(()) { |
| … |
| void ** GTY ((use_param, …)) entries; |
| … |
| } htab_t; |
| </pre></div> |
| <p>and then declare variables like this: |
| </p><div class="smallexample"> |
| <pre class="smallexample"> static htab_t GTY ((param_is (union tree_node))) ict; |
| </pre></div> |
| |
| <a name="index-paramn_005fis"></a> |
| <a name="index-use_005fparamn"></a> |
| </dd> |
| <dt><code>param<var>n</var>_is (<var>type</var>)</code></dt> |
| <dt><code>use_param<var>n</var></code></dt> |
| <dd> |
| <p>In more complicated cases, the data structure might need to work on |
| several different types, which might not necessarily all be pointers. |
| For this, <code>param1_is</code> through <code>param9_is</code> may be used to |
| specify the real type of a field identified by <code>use_param1</code> through |
| <code>use_param9</code>. |
| </p> |
| <a name="index-use_005fparams"></a> |
| </dd> |
| <dt><code>use_params</code></dt> |
| <dd> |
| <p>When a structure contains another structure that is parameterized, |
| there’s no need to do anything special, the inner structure inherits the |
| parameters of the outer one. When a structure contains a pointer to a |
| parameterized structure, the type machinery won’t automatically detect |
| this (it could, it just doesn’t yet), so it’s necessary to tell it that |
| the pointed-to structure should use the same parameters as the outer |
| structure. This is done by marking the pointer with the |
| <code>use_params</code> option. |
| </p> |
| <a name="index-deletable"></a> |
| </dd> |
| <dt><code>deletable</code></dt> |
| <dd> |
| <p><code>deletable</code>, when applied to a global variable, indicates that when |
| garbage collection runs, there’s no need to mark anything pointed to |
| by this variable, it can just be set to <code>NULL</code> instead. This is used |
| to keep a list of free structures around for re-use. |
| </p> |
| <a name="index-if_005fmarked"></a> |
| </dd> |
| <dt><code>if_marked ("<var>expression</var>")</code></dt> |
| <dd> |
| <p>Suppose you want some kinds of object to be unique, and so you put them |
| in a hash table. If garbage collection marks the hash table, these |
| objects will never be freed, even if the last other reference to them |
| goes away. GGC has special handling to deal with this: if you use the |
| <code>if_marked</code> option on a global hash table, GGC will call the |
| routine whose name is the parameter to the option on each hash table |
| entry. If the routine returns nonzero, the hash table entry will |
| be marked as usual. If the routine returns zero, the hash table entry |
| will be deleted. |
| </p> |
| <p>The routine <code>ggc_marked_p</code> can be used to determine if an element |
| has been marked already; in fact, the usual case is to use |
| <code>if_marked ("ggc_marked_p")</code>. |
| </p> |
| <a name="index-mark_005fhook"></a> |
| </dd> |
| <dt><code>mark_hook ("<var>hook-routine-name</var>")</code></dt> |
| <dd> |
| <p>If provided for a structure or union type, the given |
| <var>hook-routine-name</var> (between double-quotes) is the name of a |
| routine called when the garbage collector has just marked the data as |
| reachable. This routine should not change the data, or call any ggc |
| routine. Its only argument is a pointer to the just marked (const) |
| structure or union. |
| </p> |
| <a name="index-maybe_005fundef"></a> |
| </dd> |
| <dt><code>maybe_undef</code></dt> |
| <dd> |
| <p>When applied to a field, <code>maybe_undef</code> indicates that it’s OK if |
| the structure that this fields points to is never defined, so long as |
| this field is always <code>NULL</code>. This is used to avoid requiring |
| backends to define certain optional structures. It doesn’t work with |
| language frontends. |
| </p> |
| <a name="index-nested_005fptr"></a> |
| </dd> |
| <dt><code>nested_ptr (<var>type</var>, "<var>to expression</var>", "<var>from expression</var>")</code></dt> |
| <dd> |
| <p>The type machinery expects all pointers to point to the start of an |
| object. Sometimes for abstraction purposes it’s convenient to have |
| a pointer which points inside an object. So long as it’s possible to |
| convert the original object to and from the pointer, such pointers |
| can still be used. <var>type</var> is the type of the original object, |
| the <var>to expression</var> returns the pointer given the original object, |
| and the <var>from expression</var> returns the original object given |
| the pointer. The pointer will be available using the <code>%h</code> |
| escape. |
| </p> |
| <a name="index-chain_005fnext"></a> |
| <a name="index-chain_005fprev"></a> |
| <a name="index-chain_005fcircular"></a> |
| </dd> |
| <dt><code>chain_next ("<var>expression</var>")</code></dt> |
| <dt><code>chain_prev ("<var>expression</var>")</code></dt> |
| <dt><code>chain_circular ("<var>expression</var>")</code></dt> |
| <dd> |
| <p>It’s helpful for the type machinery to know if objects are often |
| chained together in long lists; this lets it generate code that uses |
| less stack space by iterating along the list instead of recursing down |
| it. <code>chain_next</code> is an expression for the next item in the list, |
| <code>chain_prev</code> is an expression for the previous item. For singly |
| linked lists, use only <code>chain_next</code>; for doubly linked lists, use |
| both. The machinery requires that taking the next item of the |
| previous item gives the original item. <code>chain_circular</code> is similar |
| to <code>chain_next</code>, but can be used for circular single linked lists. |
| </p> |
| <a name="index-reorder"></a> |
| </dd> |
| <dt><code>reorder ("<var>function name</var>")</code></dt> |
| <dd> |
| <p>Some data structures depend on the relative ordering of pointers. If |
| the precompiled header machinery needs to change that ordering, it |
| will call the function referenced by the <code>reorder</code> option, before |
| changing the pointers in the object that’s pointed to by the field the |
| option applies to. The function must take four arguments, with the |
| signature ‘<samp>void *, void *, <span class="nolinebreak">gt_pointer_operator,</span> void *<!-- /@w --></samp>’. |
| The first parameter is a pointer to the structure that contains the |
| object being updated, or the object itself if there is no containing |
| structure. The second parameter is a cookie that should be ignored. |
| The third parameter is a routine that, given a pointer, will update it |
| to its correct new value. The fourth parameter is a cookie that must |
| be passed to the second parameter. |
| </p> |
| <p>PCH cannot handle data structures that depend on the absolute values |
| of pointers. <code>reorder</code> functions can be expensive. When |
| possible, it is better to depend on properties of the data, like an ID |
| number or the hash of a string instead. |
| </p> |
| <a name="index-variable_005fsize"></a> |
| </dd> |
| <dt><code>variable_size</code></dt> |
| <dd> |
| <p>The type machinery expects the types to be of constant size. When this |
| is not true, for example, with structs that have array fields or unions, |
| the type machinery cannot tell how many bytes need to be allocated at |
| each allocation. The <code>variable_size</code> is used to mark such types. |
| The type machinery then provides allocators that take a parameter |
| indicating an exact size of object being allocated. Note that the size |
| must be provided in bytes whereas the <code>length</code> option works with |
| array lengths in number of elements. |
| </p> |
| <p>For example, |
| </p><div class="smallexample"> |
| <pre class="smallexample">struct GTY((variable_size)) sorted_fields_type { |
| int len; |
| tree GTY((length ("%h.len"))) elts[1]; |
| }; |
| </pre></div> |
| |
| <p>Then the objects of <code>struct sorted_fields_type</code> are allocated in GC |
| memory as follows: |
| </p><div class="smallexample"> |
| <pre class="smallexample"> field_vec = ggc_alloc_sorted_fields_type (size); |
| </pre></div> |
| |
| <p>If <var>field_vec->elts</var> stores <var>n</var> elements, then <var>size</var> |
| could be calculated as follows: |
| </p><div class="smallexample"> |
| <pre class="smallexample"> size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree); |
| </pre></div> |
| |
| <a name="index-atomic"></a> |
| </dd> |
| <dt><code>atomic</code></dt> |
| <dd> |
| <p>The <code>atomic</code> option can only be used with pointers. It informs |
| the GC machinery that the memory that the pointer points to does not |
| contain any pointers, and hence it should be treated by the GC and PCH |
| machinery as an “atomic” block of memory that does not need to be |
| examined when scanning memory for pointers. In particular, the |
| machinery will not scan that memory for pointers to mark them as |
| reachable (when marking pointers for GC) or to relocate them (when |
| writing a PCH file). |
| </p> |
| <p>The <code>atomic</code> option differs from the <code>skip</code> option. |
| <code>atomic</code> keeps the memory under Garbage Collection, but makes the |
| GC ignore the contents of the memory. <code>skip</code> is more drastic in |
| that it causes the pointer and the memory to be completely ignored by |
| the Garbage Collector. So, memory marked as <code>atomic</code> is |
| automatically freed when no longer reachable, while memory marked as |
| <code>skip</code> is not. |
| </p> |
| <p>The <code>atomic</code> option must be used with great care, because all |
| sorts of problem can occur if used incorrectly, that is, if the memory |
| the pointer points to does actually contain a pointer. |
| </p> |
| <p>Here is an example of how to use it: |
| </p><div class="smallexample"> |
| <pre class="smallexample">struct GTY(()) my_struct { |
| int number_of_elements; |
| unsigned int * GTY ((atomic)) elements; |
| }; |
| </pre></div> |
| <p>In this case, <code>elements</code> is a pointer under GC, and the memory it |
| points to needs to be allocated using the Garbage Collector, and will |
| be freed automatically by the Garbage Collector when it is no longer |
| referenced. But the memory that the pointer points to is an array of |
| <code>unsigned int</code> elements, and the GC must not try to scan it to |
| find pointers to mark or relocate, which is why it is marked with the |
| <code>atomic</code> option. |
| </p> |
| <p>Note that, currently, global variables can not be marked with |
| <code>atomic</code>; only fields of a struct can. This is a known |
| limitation. It would be useful to be able to mark global pointers |
| with <code>atomic</code> to make the PCH machinery aware of them so that |
| they are saved and restored correctly to PCH files. |
| </p> |
| <a name="index-special"></a> |
| </dd> |
| <dt><code>special ("<var>name</var>")</code></dt> |
| <dd> |
| <p>The <code>special</code> option is used to mark types that have to be dealt |
| with by special case machinery. The parameter is the name of the |
| special case. See <samp>gengtype.c</samp> for further details. Avoid |
| adding new special cases unless there is no other alternative. |
| </p> |
| <a name="index-user"></a> |
| </dd> |
| <dt><code>user</code></dt> |
| <dd> |
| <p>The <code>user</code> option indicates that the code to mark structure |
| fields is completely handled by user-provided routines. See section |
| <a href="User-GC.html#User-GC">User GC</a> for details on what functions need to be provided. |
| </p></dd> |
| </dl> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="Inheritance-and-GTY.html#Inheritance-and-GTY" accesskey="n" rel="next">Inheritance and GTY</a>, Up: <a href="Type-Information.html#Type-Information" accesskey="u" rel="up">Type Information</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| |
| |
| |
| </body> |
| </html> |