[hellogcc] [patch 7 gty.texi]: Update gccint-zh trunk to upstreams r179462
- From: Yao Qi <qiyaoltc@xxxxxxxxx>
- To: hellogcc@xxxxxxxxxxxxx
- Date: Fri, 7 Oct 2011 22:14:12 +0800
On Fri, Oct 07, 2011 at 09:47:15PM +0800, Yao Qi wrote:
> 这个patch是fsf gcc doc目录下边和gccint有关文件从 r170935到
> r179462的修改。我们gccint-zh trunk也是根据这个patch进行修改。
>
> --
> Yao Qi <qiyaoltc AT gmail DOT com>
>
> Index: gty.texi
> ===================================================================
> --- gty.texi (revision 170935)
> +++ gty.texi (revision 179462)
> @@ -371,7 +371,7 @@
> @};
> @end smallexample
>
> -Then the objects of @code{struct sorted_fields_type} are allocated in GC
> +Then the objects of @code{struct sorted_fields_type} are allocated in GC
> memory as follows:
> @smallexample
> field_vec = ggc_alloc_sorted_fields_type (size);
> @@ -383,6 +383,51 @@
> size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree);
> @end smallexample
>
> +@findex atomic
> +@item atomic
> +
> +The @code{atomic} 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).
> +
> +The @code{atomic} option differs from the @code{skip} option.
> +@code{atomic} keeps the memory under Garbage Collection, but makes the
> +GC ignore the contents of the memory. @code{skip} 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} is
> +automatically freed when no longer reachable, while memory marked as
> +@code{skip} is not.
> +
> +The @code{atomic} 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.
> +
> +Here is an example of how to use it:
> +@smallexample
> +struct GTY(()) my_struct @{
> + int number_of_elements;
> + unsigned int GTY ((atomic)) * elements;
> +@};
> +@end smallexample
> +In this case, @code{elements} 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} 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} option.
> +
> +Note that, currently, global variables can not be marked with
> +@code{atomic}; 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} to make the PCH machinery aware of them so that
> +they are saved and restored correctly to PCH files.
> +
> @findex special
> @item special ("@var{name}")
>
>
--
Yao Qi <qiyaoltc AT gmail DOT com>
Harp not on that string.
-- William Shakespeare, "Henry VI"
Index: gty.texi
===================================================================
--- gty.texi (revision 374)
+++ gty.texi (working copy)
@@ -446,6 +446,52 @@
size_t size = sizeof (struct sorted_fields_type) + n * sizeof
(tree);
@end smallexample
+@findex atomic
+@item atomic
+
+The @code{atomic} 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).
+
+The @code{atomic} option differs from the @code{skip} option.
+@code{atomic} keeps the memory under Garbage Collection, but makes
the
+GC ignore the contents of the memory. @code{skip} 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} is
+automatically freed when no longer reachable, while memory marked as
+@code{skip} is not.
+
+The @code{atomic} 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.
+
+Here is an example of how to use it:
+@smallexample
+struct GTY(()) my_struct @{
+ int number_of_elements;
+ unsigned int GTY ((atomic)) * elements;
+@};
+@end smallexample
+In this case, @code{elements} 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} 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} option.
+
+Note that, currently, global variables can not be marked with
+@code{atomic}; 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} to make the PCH machinery aware of them so that
+they are saved and restored correctly to PCH files.
+
+
@findex special
@item special ("@var{name}")
Other related posts:
- » [hellogcc] [patch 7 gty.texi]: Update gccint-zh trunk to upstreams r179462 - Yao Qi
