[2/3] tm.texi documentation on macro PREFERRED_RENAME_CLASS

tm.texi is a generated file.  You need to patch tm.texi.in and regenerate 
tm.texi.

In general new target macros should be avoided in favour of hooks (whose 
documentation source should be in target.def with a minimal @hook 
reference in tm.texi.in) unless one of the following applies:

* The macro is used in code built for the target, #if conditions, enum 
values, case labels or other places where a compile-time constant is 
required and so a hook cannot be used.

* The macro is so closely related to an existing set of macros that it 
does not make sense for some to be macros and others to be hooks; all 
should be converted at once.  (For example, when I added stdint.h support 
I added a set of macros such as INT_FAST8_TYPE.  These work almost the 
same as others such as SIZE_TYPE and all should be converted to hooks at 
once.  The appropriate hook conversion would not be one hook per macro; 
more likely, one for the miscellaneous C types such as SIZE_TYPE, one for 
SIG_ATOMIC_TYPE and one for the stdint.h types.  The hooks would not 
return strings like the macros do; they'd take enum values and return enum 
values, although an intermediate stage might be macros evaluating to enum 
values.)

* (Until the relevant parts of 
<http://gcc.gnu.org/ml/gcc/2010-10/msg00294.html> are implemented for the 
relevant part of the compiler.)  The macro is used somewhere without a 
hook facility at present, such as the driver or collect2.

* There is actual evidence of significant performance cost from using a 
hook.  (In general, however, the long-term plan is for LTO-based 
devirtualization to remove the performance penalty of hooks.  
<http://gcc.gnu.org/ml/gcc-patches/2010-06/msg02826.html> suggests this 
devirtualization wasn't usefully happening as of June, both because the 
target structure isn't const and because devirtualization happens too late 
for inlining.  I don't know if it's since moved on to be able to detect 
which fields of the structure are unmodified or to devirtualize earlier.)

On 10/22/2010 06:04 AM, Joseph S. Myers wrote:
> tm.texi is a generated file.  You need to patch tm.texi.in and regenerate 
> tm.texi.
> 
> In general new target macros should be avoided in favour of hooks (whose 
> documentation source should be in target.def with a minimal @hook 
> reference in tm.texi.in) unless one of the following applies:
> 

Joseph,
Thanks for this good explanation.  I'll convert my target macro to hook.
Paolo, Anatoly,
Thanks for your review too.  I'll update my patches, and submit them again.

> * The macro is used in code built for the target, #if conditions, enum 
> values, case labels or other places where a compile-time constant is 
> required and so a hook cannot be used.
> 
> * The macro is so closely related to an existing set of macros that it 
> does not make sense for some to be macros and others to be hooks; all 
> should be converted at once.  (For example, when I added stdint.h support 
> I added a set of macros such as INT_FAST8_TYPE.  These work almost the 
> same as others such as SIZE_TYPE and all should be converted to hooks at 
> once.  The appropriate hook conversion would not be one hook per macro; 
> more likely, one for the miscellaneous C types such as SIZE_TYPE, one for 
> SIG_ATOMIC_TYPE and one for the stdint.h types.  The hooks would not 
> return strings like the macros do; they'd take enum values and return enum 
> values, although an intermediate stage might be macros evaluating to enum 
> values.)
> 
> * (Until the relevant parts of 
> <http://gcc.gnu.org/ml/gcc/2010-10/msg00294.html> are implemented for the 
> relevant part of the compiler.)  The macro is used somewhere without a 
> hook facility at present, such as the driver or collect2.
> 
> * There is actual evidence of significant performance cost from using a 
> hook.  (In general, however, the long-term plan is for LTO-based 
> devirtualization to remove the performance penalty of hooks.  
> <http://gcc.gnu.org/ml/gcc-patches/2010-06/msg02826.html> suggests this 
> devirtualization wasn't usefully happening as of June, both because the 
> target structure isn't const and because devirtualization happens too late 
> for inlining.  I don't know if it's since moved on to be able to detect 
> which fields of the structure are unmodified or to devirtualize earlier.)
>