From fc72b3800247719e3cde796bc36f860ae4c74d7b Mon Sep 17 00:00:00 2001 From: Jason Merrill Date: Wed, 7 Jul 2004 13:38:40 -0400 Subject: [PATCH] re PR c++/15815 (Update #pragma interface and #pragma implementation documentation.) PR c++/15815 * doc/extend.texi (C++ Interface): Correct information and discourage use. From-SVN: r84210 --- gcc/ChangeLog | 6 ++++++ gcc/doc/extend.texi | 52 +++++++++++++++------------------------------ 2 files changed, 23 insertions(+), 35 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index e5635432e0f..0363968fb32 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,9 @@ +2004-07-07 Jason Merrill + + PR c++/15815 + * doc/extend.texi (C++ Interface): Correct information and + discourage use. + 2004-07-07 Vladimir Makarov PR target/16130 diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 0d2798f2a1e..4f9b9d922be 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -7940,37 +7940,25 @@ almost certainly break things. another way to control placement of these constructs. @node C++ Interface -@section Declarations and Definitions in One Header +@section #pragma interface and implementation @cindex interface and implementation headers, C++ @cindex C++ interface and implementation headers -C++ object definitions can be quite complex. In principle, your source -code will need two kinds of things for each object that you use across -more than one source file. First, you need an @dfn{interface} -specification, describing its structure with type declarations and -function prototypes. Second, you need the @dfn{implementation} itself. -It can be tedious to maintain a separate interface description in a -header file, in parallel to the actual implementation. It is also -dangerous, since separate interface and implementation definitions may -not remain parallel. - @cindex pragmas, interface and implementation -With GNU C++, you can use a single header file for both purposes. -@quotation -@emph{Warning:} The mechanism to specify this is in transition. For the -nonce, you must use one of two @code{#pragma} commands; in a future -release of GNU C++, an alternative mechanism will make these -@code{#pragma} commands unnecessary. -@end quotation +@code{#pragma interface} and @code{#pragma implementation} provide the +user with a way of explicitly directing the compiler to emit entities +with vague linkage (and debugging information) in a particular +translation unit. -The header file contains the full definitions, but is marked with -@samp{#pragma interface} in the source code. This allows the compiler -to use the header file only as an interface specification when ordinary -source files incorporate it with @code{#include}. In the single source -file where the full implementation belongs, you can use either a naming -convention or @samp{#pragma implementation} to indicate this alternate -use of the header file. +@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in +most cases, because of COMDAT support and the ``key method'' heuristic +mentioned in @ref{Vague Linkage}. Using them can actually cause your +program to grow due to unnecesary out-of-line copies of inline +functions. Currently (3.4) the only benefit of these +@code{#pragma}s is reduced duplication of debugging information, and +that should be addressed soon on DWARF 2 targets with the use of +COMDAT groups. @table @code @item #pragma interface @@ -8020,9 +8008,6 @@ an implementation file whenever you would include it from implementation}. This was deemed to be more trouble than it was worth, however, and disabled. -If you use an explicit @samp{#pragma implementation}, it must appear in -your source file @emph{before} you include the affected header files. - Use the string argument if you want a single implementation file to include code from multiple header files. (You must also use @samp{#include} to include the header file; @samp{#pragma @@ -8040,10 +8025,10 @@ multiple implementation files. effect on function inlining. If you define a class in a header file marked with @samp{#pragma -interface}, the effect on a function defined in that class is similar to -an explicit @code{extern} declaration---the compiler emits no code at -all to define an independent version of the function. Its definition -is used only for inlining with its callers. +interface}, the effect on an inline function defined in that class is +similar to an explicit @code{extern} declaration---the compiler emits +no code at all to define an independent version of the function. Its +definition is used only for inlining with its callers. @opindex fno-implement-inlines Conversely, when you include the same header file in a main source file @@ -8194,9 +8179,6 @@ management. Code written for the Borland model will work fine, but each translation unit will contain instances of each of the templates it uses. In a large program, this can lead to an unacceptable amount of code duplication. - -@xref{C++ Interface,,Declarations and Definitions in One Header}, for -more discussion of these pragmas. @end enumerate @node Bound member functions -- 2.30.2