-@c Copyright (C) 1988,89,92,93,94,96 Free Software Foundation, Inc.
+@c Copyright (C) 1988,89,92,93,94,96,98, 99 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
* Long Long:: Double-word integers---@code{long long int}.
* Complex:: Data types for complex numbers.
+* Hex Floats:: Hexadecimal floating-point constants.
* Zero Length:: Zero-length arrays.
* Variable Length:: Arrays whose length is computed at run time.
* Macro Varargs:: Macros with variable number of arguments.
* Function Names:: Printable strings which are the name of the current
function.
* Return Address:: Getting the return or frame address of a function.
+* Other Builtins:: Other built-in functions.
+* Deprecated Features:: Things might disappear from g++.
@end menu
@end ifset
@ifclear INTERNALS
* Conditionals:: Omitting the middle operand of a @samp{?:} expression.
* Long Long:: Double-word integers---@code{long long int}.
* Complex:: Data types for complex numbers.
+* Hex Floats:: Hexadecimal floating-point constants.
* Zero Length:: Zero-length arrays.
* Variable Length:: Arrays whose length is computed at run time.
* Macro Varargs:: Macros with variable number of arguments.
* Function Names:: Printable strings which are the name of the current
function.
* Return Address:: Getting the return or frame address of a function.
+* Deprecated Features:: Things might disappear from g++.
+* Other Builtins:: Other built-in functions.
@end menu
@end ifclear
The labels within the interpreter function can be stored in the
threaded code for super-fast dispatching.
-You can use this mechanism to jump to code in a different function. If
-you do that, totally unpredictable things will happen. The best way to
+You may not use this mechanism to jump to code in a different function.
+If you do that, totally unpredictable things will happen. The best way to
avoid this is to store the label address only in automatic variables and
never pass it as an argument.
+An alternate way to write the above example is
+
+@example
+static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, &&hack - &&foo @};
+goto *(&&foo + array[i]);
+@end example
+
+@noindent
+This is more friendly to code living in shared libraries, as it reduces
+the number of dynamic relocations that are needed, and by consequence,
+allows the data to be read-only.
+
@node Nested Functions
@section Nested Functions
@cindex nested functions
safe.
GNU CC implements taking the address of a nested function using a
-technique called @dfn{trampolines}. A paper describing them is
-available from @samp{maya.idiap.ch} in directory @file{pub/tmb},
-file @file{usenix88-lexic.ps.Z}.
+technique called @dfn{trampolines}. A paper describing them is
+available as @samp{http://master.debian.org/~karlheg/Usenix88-lexic.pdf}.
A nested function can jump to a label inherited from a containing
function, provided the label was explicitly declared in the containing
A future version of GDB will know how to recognize such pairs and treat
them as a single variable with a complex type.
+@node Hex Floats
+@section Hex Floats
+@cindex hex floats
+
+GNU CC recognizes floating-point numbers writen not only in the usual
+decimal notation, such as @code{1.55e1}, but also numbers such as
+@code{0x1.fp3} written in hexadecimal format. In that format the
+@code{0x} hex introducer and the @code{p} or @code{P} exponent field are
+mandatory. The exponent is a decimal number that indicates the power of
+2 by which the significand part will be multiplied. Thus @code{0x1.f} is
+1 15/16, @code{p3} multiplies it by 8, and the value of @code{0x1.fp3}
+is the same as @code{1.55e1}.
+
+Unlike for floating-point numbers in the decimal notation the exponent
+is always required in the hexadecimal notation. Otherwise the compiler
+would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
+could mean @code{1.0f} or @code{1.9375} since @code{f} is also the
+extension for floating-point constants of type @code{float}.
+
@node Zero Length
@section Arrays of Length Zero
@cindex arrays of length zero
@cindex functions that never return
@cindex functions that have no side effects
@cindex functions in arbitrary sections
+@cindex functions that bahave like malloc
@cindex @code{volatile} applied to function
@cindex @code{const} applied to function
-@cindex functions with @code{printf} or @code{scanf} style arguments
+@cindex functions with @code{printf}, @code{scanf} or @code{strftime} style arguments
@cindex functions that are passed arguments in registers on the 386
@cindex functions that pop the argument stack on the 386
@cindex functions that do not pop the argument stack on the 386
The keyword @code{__attribute__} allows you to specify special
attributes when making a declaration. This keyword is followed by an
-attribute specification inside double parentheses. Eight attributes,
-@code{noreturn}, @code{const}, @code{format}, @code{section},
-@code{constructor}, @code{destructor}, @code{unused} and @code{weak} are
+attribute specification inside double parentheses. Ten attributes,
+@code{noreturn}, @code{const}, @code{format},
+@code{no_instrument_function}, @code{section}, @code{constructor},
+@code{destructor}, @code{unused}, @code{weak} and @code{malloc} are
currently defined for functions. Other attributes, including
@code{section} are supported for variables declarations (@pxref{Variable
Attributes}) and for types (@pxref{Type Attributes}).
@item format (@var{archetype}, @var{string-index}, @var{first-to-check})
@cindex @code{format} function attribute
-The @code{format} attribute specifies that a function takes @code{printf}
-or @code{scanf} style arguments which should be type-checked against a
-format string. For example, the declaration:
+The @code{format} attribute specifies that a function takes @code{printf},
+@code{scanf}, or @code{strftime} style arguments which should be type-checked
+against a format string. For example, the declaration:
@smallexample
extern int
@code{my_format}.
The parameter @var{archetype} determines how the format string is
-interpreted, and should be either @code{printf} or @code{scanf}. The
+interpreted, and should be either @code{printf}, @code{scanf}, or
+@code{strftime}. The
parameter @var{string-index} specifies which argument is the format
string argument (starting from 1), while @var{first-to-check} is the
number of the first argument to check against the format string. For
which take format strings as arguments, so that GNU CC can check the
calls to these functions for errors. The compiler always checks formats
for the ANSI library functions @code{printf}, @code{fprintf},
-@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf},
+@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
warnings are requested (using @samp{-Wformat}), so there is no need to
modify the header file @file{stdio.h}.
@noindent
causes the compiler to check the arguments in calls to
-@code{my_dgettext} whose result is passed to a @code{printf} or
-@code{scanf} type function for consistency with the @code{printf} style
-format string argument @code{my_format}.
+@code{my_dgettext} whose result is passed to a @code{printf},
+@code{scanf}, or @code{strftime} type function for consistency with the
+@code{printf} style format string argument @code{my_format}.
The parameter @var{string-index} specifies which argument is the format
string argument (starting from 1).
The @code{format-arg} attribute allows you to identify your own
functions which modify format strings, so that GNU CC can check the
-calls to @code{printf} and @code{scanf} function whose operands are a
-call to one of your own function. The compiler always treats
-@code{gettext}, @code{dgettext}, and @code{dcgettext} in this manner.
+calls to @code{printf}, @code{scanf}, or @code{strftime} function whose
+operands are a call to one of your own function. The compiler always
+treats @code{gettext}, @code{dgettext}, and @code{dcgettext} in this
+manner.
+
+@item no_instrument_function
+@cindex @code{no_instrument_function} function attribute
+If @samp{-finstrument-functions} is given, profiling function calls will
+be generated at entry and exit of most user-compiled functions.
+Functions with this attribute will not be so instrumented.
@item section ("section-name")
@cindex @code{section} function attribute
for ELF targets, and also for a.out targets when using the GNU assembler
and linker.
+@item malloc
+@cindex @code{malloc} attribute
+The @code{malloc} attribute is used to tell the compiler that a function
+may be treated as if it were the malloc function. The compiler assumes
+that calls to malloc result in a pointers that cannot alias anything.
+This will often improve optimization.
+
@item alias ("target")
@cindex @code{alias} attribute
The @code{alias} attribute causes the declaration to be emitted as an
declares @samp{f} to be a weak alias for @samp{__f}. In C++, the
mangled name for the target must be used.
+Not all target machines support this attribute.
+
+@item no_check_memory_usage
+@cindex @code{no_check_memory_usage} function attribute
+The @code{no_check_memory_usage} attribute causes GNU CC to omit checks
+of memory references when it generates code for that function. Normally
+if you specify @samp{-fcheck-memory-usage} (see @pxref{Code Gen
+Options}), GNU CC generates calls to support routines before most memory
+accesses to permit support code to record usage and detect uses of
+uninitialized or unallocated storage. Since GNU CC cannot handle
+@code{asm} statements properly they are not allowed in such functions.
+If you declare a function with this attribute, GNU CC will not generate
+memory checking code for that function, permitting the use of @code{asm}
+statements without having to compile that function with different
+options. This also allows you to write support routines of your own if
+you wish, without getting infinite recursion if they get compiled with
+@code{-fcheck-memory-usage}.
+
@item regparm (@var{number})
@cindex functions that are passed arguments in registers on the 386
On the Intel 386, the @code{regparm} attribute causes the compiler to
The compiler will generate more efficient code for loads and stores
on data in the tiny data section. Note the tiny data area is limited to
slightly under 32kbytes of data.
+
+@item interrupt
+@cindex interrupt handlers on the M32R/D
+Use this option on the M32R/D to indicate that the specified
+function is an interrupt handler. The compiler will generate function
+entry and exit sequences suitable for use in an interrupt handler when this
+attribute is present.
+
+@item model (@var{model-name})
+@cindex function addressability on the M32R/D
+Use this attribute on the M32R/D to set the addressability of an object,
+and the code generated for a function.
+The identifier @var{model-name} is one of @code{small}, @code{medium},
+or @code{large}, representing each of the code models.
+
+Small model objects live in the lower 16MB of memory (so that their
+addresses can be loaded with the @code{ld24} instruction), and are
+callable with the @code{bl} instruction.
+
+Medium model objects may live anywhere in the 32 bit address space (the
+compiler will generate @code{seth/add3} instructions to load their addresses),
+and are callable with the @code{bl} instruction.
+
+Large model objects may live anywhere in the 32 bit address space (the
+compiler will generate @code{seth/add3} instructions to load their addresses),
+and may not be reachable with the @code{bl} instruction (the compiler will
+generate the much slower @code{seth/add3/jl} instruction sequence).
+
@end table
You can specify multiple attributes in a declaration by separating them
@example
/* @r{Use prototypes unless the compiler is old-fashioned.} */
-#if __STDC__
+#ifdef __STDC__
#define P(x) x
#else
#define P(x) ()
If you need to map the entire contents of a module to a particular
section, consider using the facilities of the linker instead.
+@item shared
+@cindex @code{shared} variable attribute
+On Windows NT, in addition to nputting variable definitions in a named
+section, the section can also be shared among all running copies of an
+executable or DLL. For example, this small program defines shared data
+by putting it in a named section "shared" and marking the section
+shareable:
+
+@smallexample
+int foo __attribute__((section ("shared"), shared)) = 0;
+
+int
+main()
+@{
+ /* Read and write foo. All running copies see the same value. */
+ return 0;
+@}
+@end smallexample
+
+@noindent
+You may only use the @code{shared} attribute along with @code{section}
+attribute with a fully initialized global definition because of the way
+linkers work. See @code{section} attribute for more information.
+
+The @code{shared} attribute is only available on Windows NT.
+
@item transparent_union
This attribute, attached to a function parameter which is a union, means
that the corresponding argument may have the type of any union member,
@item weak
The @code{weak} attribute is described in @xref{Function Attributes}.
+
+@item model (@var{model-name})
+@cindex variable addressability on the M32R/D
+Use this attribute on the M32R/D to set the addressability of an object.
+The identifier @var{model-name} is one of @code{small}, @code{medium},
+or @code{large}, representing each of the code models.
+
+Small model objects live in the lower 16MB of memory (so that their
+addresses can be loaded with the @code{ld24} instruction).
+
+Medium and large model objects may live anywhere in the 32 bit address space
+(the compiler will generate @code{seth/add3} instructions to load their
+addresses).
+
@end table
To specify multiple attributes, separate them by commas within the
@emph{definition} and the @code{packed} attribute only past the closing
brace of a definition.
+You may also specify attributes between the enum, struct or union
+tag and the name of the type rather than after the closing brace.
+
@table @code
@cindex @code{aligned} attribute
@item aligned (@var{alignment})
of the specified type. For example, the declarations:
@smallexample
-struct S @{ short f[3]; @} __attribute__ ((aligned (8));
-typedef int more_aligned_int __attribute__ ((aligned (8));
+struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
+typedef int more_aligned_int __attribute__ ((aligned (8)));
@end smallexample
@noindent
-force the compiler to insure (as fas as it can) that each variable whose
+force the compiler to insure (as far as it can) that each variable whose
type is @code{struct S} or @code{more_aligned_int} will be allocated and
aligned @emph{at least} on a 8-byte boundary. On a Sparc, having all
variables of type @code{struct S} aligned to 8-byte boundaries allows
attribute on all @code{enum} definitions.
You may only specify this attribute after a closing curly brace on an
-@code{enum} definition, not in a @code{typedef} declaration.
+@code{enum} definition, not in a @code{typedef} declaration, unless that
+declaration also contains the definition of the @code{enum}.
@item transparent_union
This attribute, attached to a @code{union} type definition, indicates
return waitpid (-1, p.__ip, 0);
@}
@end example
+
+@item unused
+When attached to a type (including a @code{union} or a @code{struct}),
+this attribute means that variables of that type are meant to appear
+possibly unused. GNU CC will not produce a warning for any variables of
+that type, even if the variable appears to do nothing. This is often
+the case with lock or thread classes, which are usually defined and then
+not referenced, but contain constructors and destructors that have
+nontrivial bookkeeping functions.
+
@end table
To specify multiple attributes, separate them by commas within the
(If you are writing a header file to be included in ANSI C programs, write
@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
-
You can also make all ``simple enough'' functions inline with the option
-@samp{-finline-functions}. Note that certain usages in a function
-definition can make it unsuitable for inline substitution.
+@samp{-finline-functions}.
+
+Note that certain usages in a function definition can make it unsuitable
+for inline substitution. Among these usages are: use of varargs, use of
+alloca, use of variable sized data types (@pxref{Variable Length}),
+use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
+and nested functions (@pxref{Nested Functions}). Using @samp{-Winline}
+will warn when a function marked @code{inline} could not be substituted,
+and will give the reason for the failure.
Note that in C and Objective C, unlike C++, the @code{inline} keyword
does not affect the linkage of the function.
@cindex assembler instructions
@cindex registers
-In an assembler instruction using @code{asm}, you can now specify the
-operands of the instruction using C expressions. This means no more
-guessing which registers or memory locations will contain the data you want
+In an assembler instruction using @code{asm}, you can specify the
+operands of the instruction using C expressions. This means you need not
+guess which registers or memory locations will contain the data you want
to use.
-You must specify an assembler instruction template much like what appears
-in a machine description, plus an operand constraint string for each
-operand.
+You must specify an assembler instruction template much like what
+appears in a machine description, plus an operand constraint string for
+each operand.
For example, here is how to use the 68881's @code{fsinx} instruction:
@noindent
Here @code{angle} is the C expression for the input operand while
@code{result} is that of the output operand. Each has @samp{"f"} as its
-operand constraint, saying that a floating point register is required. The
-@samp{=} in @samp{=f} indicates that the operand is an output; all output
-operands' constraints must use @samp{=}. The constraints use the same
-language used in the machine description (@pxref{Constraints}).
-
-Each operand is described by an operand-constraint string followed by the C
-expression in parentheses. A colon separates the assembler template from
-the first output operand, and another separates the last output operand
-from the first input, if any. Commas separate output operands and separate
-inputs. The total number of operands is limited to ten or to the maximum
-number of operands in any instruction pattern in the machine description,
-whichever is greater.
-
-If there are no output operands, and there are input operands, then there
-must be two consecutive colons surrounding the place where the output
+operand constraint, saying that a floating point register is required.
+The @samp{=} in @samp{=f} indicates that the operand is an output; all
+output operands' constraints must use @samp{=}. The constraints use the
+same language used in the machine description (@pxref{Constraints}).
+
+Each operand is described by an operand-constraint string followed by
+the C expression in parentheses. A colon separates the assembler
+template from the first output operand and another separates the last
+output operand from the first input, if any. Commas separate the
+operands within each group. The total number of operands is limited to
+ten or to the maximum number of operands in any instruction pattern in
+the machine description, whichever is greater.
+
+If there are no output operands but there are input operands, you must
+place two consecutive colons surrounding the place where the output
operands would go.
Output operand expressions must be lvalues; the compiler can check this.
-The input operands need not be lvalues. The compiler cannot check whether
-the operands have data types that are reasonable for the instruction being
-executed. It does not parse the assembler instruction template and does
-not know what it means, or whether it is valid assembler input. The
-extended @code{asm} feature is most often used for machine instructions
-that the compiler itself does not know exist. If the output expression
-cannot be directly addressed (for example, it is a bit field), your
-constraint must allow a register. In that case, GNU CC will use
-the register as the output of the @code{asm}, and then store that
-register into the output.
-
-The ordinary output operands must be write-only; GNU CC will assume
-that the values in these operands before the instruction are dead and
-need not be generated. Extended asm supports input-output or
-read-write operands. Use the constraint character @samp{+} to indicate
-such an operand and list it with the output operands.
-
-When the constraints for the read-write operand
-(or the operand in which only some of the bits are to be changed)
-allows a register, you may, as an alternative, logically
-split its function into two separate operands, one input operand and one
-write-only output operand. The connection between them is expressed by
-constraints which say they need to be in the same location when the
-instruction executes. You can use the same C expression for both
-operands, or different expressions. For example, here we write the
-(fictitious) @samp{combine} instruction with @code{bar} as its read-only
-source operand and @code{foo} as its read-write destination:
+The input operands need not be lvalues. The compiler cannot check
+whether the operands have data types that are reasonable for the
+instruction being executed. It does not parse the assembler instruction
+template and does not know what it means or even whether it is valid
+assembler input. The extended @code{asm} feature is most often used for
+machine instructions the compiler itself does not know exist. If
+the output expression cannot be directly addressed (for example, it is a
+bit field), your constraint must allow a register. In that case, GNU CC
+will use the register as the output of the @code{asm}, and then store
+that register into the output.
+
+The ordinary output operands must be write-only; GNU CC will assume that
+the values in these operands before the instruction are dead and need
+not be generated. Extended asm supports input-output or read-write
+operands. Use the constraint character @samp{+} to indicate such an
+operand and list it with the output operands.
+
+When the constraints for the read-write operand (or the operand in which
+only some of the bits are to be changed) allows a register, you may, as
+an alternative, logically split its function into two separate operands,
+one input operand and one write-only output operand. The connection
+between them is expressed by constraints which say they need to be in
+the same location when the instruction executes. You can use the same C
+expression for both operands, or different expressions. For example,
+here we write the (fictitious) @samp{combine} instruction with
+@code{bar} as its read-only source operand and @code{foo} as its
+read-write destination:
@example
asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
@end example
@noindent
-The constraint @samp{"0"} for operand 1 says that it must occupy the same
-location as operand 0. A digit in constraint is allowed only in an input
-operand, and it must refer to an output operand.
+The constraint @samp{"0"} for operand 1 says that it must occupy the
+same location as operand 0. A digit in constraint is allowed only in an
+input operand and it must refer to an output operand.
Only a digit in the constraint can guarantee that one operand will be in
-the same place as another. The mere fact that @code{foo} is the value of
-both operands is not enough to guarantee that they will be in the same
-place in the generated assembler code. The following would not work:
+the same place as another. The mere fact that @code{foo} is the value
+of both operands is not enough to guarantee that they will be in the
+same place in the generated assembler code. The following would not
+work reliably:
@example
asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
since the register for operand 1 is not even mentioned in the assembler
code, the result will not work, but GNU CC can't tell that.
-Some instructions clobber specific hard registers. To describe this, write
-a third colon after the input operands, followed by the names of the
-clobbered hard registers (given as strings). Here is a realistic example
-for the Vax:
+Some instructions clobber specific hard registers. To describe this,
+write a third colon after the input operands, followed by the names of
+the clobbered hard registers (given as strings). Here is a realistic
+example for the VAX:
@example
asm volatile ("movc3 %0,%1,%2"
: "r0", "r1", "r2", "r3", "r4", "r5");
@end example
+You may not write a clobber description in a way that overlaps with an
+input or output operand. For example, you may not have an operand
+describing a register class with one member if you mention that register
+in the clobber list. There is no way for you to specify that an input
+operand is modified without also specifying it as an output
+operand. Note that if all the output operands you specify are for this
+purpose (and hence unused), you will then also need to specify
+@code{volatile} for the @code{asm} construct, as described below, to
+prevent GNU CC from deleting the @code{asm} statement as unused.
+
If you refer to a particular hardware register from the assembler code,
-then you will probably have to list the register after the third colon
-to tell the compiler that the register's value is modified. In many
-assemblers, the register names begin with @samp{%}; to produce one
-@samp{%} in the assembler code, you must write @samp{%%} in the input.
-
-If your assembler instruction can alter the condition code register,
-add @samp{cc} to the list of clobbered registers. GNU CC on some
-machines represents the condition codes as a specific hardware
-register; @samp{cc} serves to name this register. On other machines,
-the condition code is handled differently, and specifying @samp{cc}
-has no effect. But it is valid no matter what the machine.
+you will probably have to list the register after the third colon to
+tell the compiler the register's value is modified. In some assemblers,
+the register names begin with @samp{%}; to produce one @samp{%} in the
+assembler code, you must write @samp{%%} in the input.
+
+If your assembler instruction can alter the condition code register, add
+@samp{cc} to the list of clobbered registers. GNU CC on some machines
+represents the condition codes as a specific hardware register;
+@samp{cc} serves to name this register. On other machines, the
+condition code is handled differently, and specifying @samp{cc} has no
+effect. But it is valid no matter what the machine.
If your assembler instruction modifies memory in an unpredictable
-fashion, add @samp{memory} to the list of clobbered registers.
-This will cause GNU CC to not keep memory values cached in
-registers across the assembler instruction.
+fashion, add @samp{memory} to the list of clobbered registers. This
+will cause GNU CC to not keep memory values cached in registers across
+the assembler instruction.
-You can put multiple assembler instructions together in a single @code{asm}
-template, separated either with newlines (written as @samp{\n}) or with
-semicolons if the assembler allows such semicolons. The GNU assembler
-allows semicolons and all Unix assemblers seem to do so. The input
-operands are guaranteed not to use any of the clobbered registers, and
-neither will the output operands' addresses, so you can read and write the
-clobbered registers as many times as you like. Here is an example of
-multiple instructions in a template; it assumes that the subroutine
-@code{_foo} accepts arguments in registers 9 and 10:
+You can put multiple assembler instructions together in a single
+@code{asm} template, separated either with newlines (written as
+@samp{\n}) or with semicolons if the assembler allows such semicolons.
+The GNU assembler allows semicolons and most Unix assemblers seem to do
+so. The input operands are guaranteed not to use any of the clobbered
+registers, and neither will the output operands' addresses, so you can
+read and write the clobbered registers as many times as you like. Here
+is an example of multiple instructions in a template; it assumes the
+subroutine @code{_foo} accepts arguments in registers 9 and 10:
@example
asm ("movl %0,r9;movl %1,r10;call _foo"
: "r9", "r10");
@end example
-Unless an output operand has the @samp{&} constraint modifier, GNU CC may
-allocate it in the same register as an unrelated input operand, on the
-assumption that the inputs are consumed before the outputs are produced.
+Unless an output operand has the @samp{&} constraint modifier, GNU CC
+may allocate it in the same register as an unrelated input operand, on
+the assumption the inputs are consumed before the outputs are produced.
This assumption may be false if the assembler code actually consists of
more than one instruction. In such a case, use @samp{&} for each output
-operand that may not overlap an input.
-@xref{Modifiers}.
+operand that may not overlap an input. @xref{Modifiers}.
-If you want to test the condition code produced by an assembler instruction,
-you must include a branch and a label in the @code{asm} construct, as follows:
+If you want to test the condition code produced by an assembler
+instruction, you must include a branch and a label in the @code{asm}
+construct, as follows:
@example
asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
and most Unix assemblers do.
Speaking of labels, jumps from one @code{asm} to another are not
-supported. The compiler's optimizers do not know about these jumps,
-and therefore they cannot take account of them when deciding how to
+supported. The compiler's optimizers do not know about these jumps, and
+therefore they cannot take account of them when deciding how to
optimize.
@cindex macros containing @code{asm}
operates on a proper @code{double} value, and to accept only those
arguments @code{x} which can convert automatically to a @code{double}.
-Another way to make sure the instruction operates on the correct data type
-is to use a cast in the @code{asm}. This is different from using a
+Another way to make sure the instruction operates on the correct data
+type is to use a cast in the @code{asm}. This is different from using a
variable @code{__arg} in that it converts more different types. For
example, if the desired type were @code{int}, casting the argument to
@code{int} would accept a pointer with no complaint, while assigning the
using a pointer unless the caller explicitly casts it.
If an @code{asm} has output operands, GNU CC assumes for optimization
-purposes that the instruction has no side effects except to change the
-output operands. This does not mean that instructions with a side effect
-cannot be used, but you must be careful, because the compiler may eliminate
-them if the output operands aren't used, or move them out of loops, or
-replace two with one if they constitute a common subexpression. Also, if
-your instruction does have a side effect on a variable that otherwise
-appears not to change, the old value of the variable may be reused later if
-it happens to be found in a register.
+purposes the instruction has no side effects except to change the output
+operands. This does not mean instructions with a side effect cannot be
+used, but you must be careful, because the compiler may eliminate them
+if the output operands aren't used, or move them out of loops, or
+replace two with one if they constitute a common subexpression. Also,
+if your instruction does have a side effect on a variable that otherwise
+appears not to change, the old value of the variable may be reused later
+if it happens to be found in a register.
You can prevent an @code{asm} instruction from being deleted, moved
significantly, or combined, by writing the keyword @code{volatile} after
the @code{asm}. For example:
@example
-#define set_priority(x) \
-asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
+#define get_and_set_priority(new) \
+(@{ int __old; \
+ asm volatile ("get_and_set_priority %0, %1": "=g" (__old) : "g" (new)); \
+ __old; @})
@end example
@noindent
-An instruction without output operands will not be deleted or moved
-significantly, regardless, unless it is unreachable.
+If you write an @code{asm} instruction with no outputs, GNU CC will know
+the instruction has side-effects and will not delete the instruction or
+move it outside of loops. If the side-effects of your instruction are
+not purely external, but will affect variables in your program in ways
+other than reading the inputs and clobbering the specified registers or
+memory, you should write the @code{volatile} keyword to prevent future
+versions of GNU CC from moving the instruction around within a core
+region.
+
+An @code{asm} instruction without any operands or clobbers (and ``old
+style'' @code{asm}) will not be deleted or moved significantly,
+regardless, unless it is unreachable, the same wasy as if you had
+written a @code{volatile} keyword.
Note that even a volatile @code{asm} instruction can be moved in ways
that appear insignificant to the compiler, such as across jump
programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
Keywords}.
+@subsection i386 floating point asm operands
+
+There are several rules on the usage of stack-like regs in
+asm_operands insns. These rules apply only to the operands that are
+stack-like regs:
+
+@enumerate
+@item
+Given a set of input regs that die in an asm_operands, it is
+necessary to know which are implicitly popped by the asm, and
+which must be explicitly popped by gcc.
+
+An input reg that is implicitly popped by the asm must be
+explicitly clobbered, unless it is constrained to match an
+output operand.
+
+@item
+For any input reg that is implicitly popped by an asm, it is
+necessary to know how to adjust the stack to compensate for the pop.
+If any non-popped input is closer to the top of the reg-stack than
+the implicitly popped reg, it would not be possible to know what the
+stack looked like --- it's not clear how the rest of the stack ``slides
+up''.
+
+All implicitly popped input regs must be closer to the top of
+the reg-stack than any input that is not implicitly popped.
+
+It is possible that if an input dies in an insn, reload might
+use the input reg for an output reload. Consider this example:
+
+@example
+asm ("foo" : "=t" (a) : "f" (b));
+@end example
+
+This asm says that input B is not popped by the asm, and that
+the asm pushes a result onto the reg-stack, ie, the stack is one
+deeper after the asm than it was before. But, it is possible that
+reload will think that it can use the same reg for both the input and
+the output, if input B dies in this insn.
+
+If any input operand uses the @code{f} constraint, all output reg
+constraints must use the @code{&} earlyclobber.
+
+The asm above would be written as
+
+@example
+asm ("foo" : "=&t" (a) : "f" (b));
+@end example
+
+@item
+Some operands need to be in particular places on the stack. All
+output operands fall in this category --- there is no other way to
+know which regs the outputs appear in unless the user indicates
+this in the constraints.
+
+Output operands must specifically indicate which reg an output
+appears in after an asm. @code{=f} is not allowed: the operand
+constraints must select a class with a single reg.
+
+@item
+Output operands may not be ``inserted'' between existing stack regs.
+Since no 387 opcode uses a read/write operand, all output operands
+are dead before the asm_operands, and are pushed by the asm_operands.
+It makes no sense to push anywhere but the top of the reg-stack.
+
+Output operands must start at the top of the reg-stack: output
+operands may not ``skip'' a reg.
+
+@item
+Some asm statements may need extra stack space for internal
+calculations. This can be guaranteed by clobbering stack registers
+unrelated to the inputs and outputs.
+
+@end enumerate
+
+Here are a couple of reasonable asms to want to write. This asm
+takes one input, which is internally popped, and produces two outputs.
+
+@example
+asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
+@end example
+
+This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode,
+and replaces them with one output. The user must code the @code{st(1)}
+clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs.
+
+@example
+asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
+@end example
+
@ifclear INTERNALS
@c Show the details on constraints if they do not appear elsewhere in
@c the manual
Local register variables in specific registers do not reserve the
registers. The compiler's data flow analysis is capable of determining
where the specified registers contain live values, and where they are
-available for other uses.
+available for other uses. Stores into local register variables may be deleted
+when they appear to be dead according to dataflow analysis. References
+to local register variables may be deleted or moved or simplified.
These local variables are sometimes convenient for use with the extended
@code{asm} feature (@pxref{Extended Asm}), if you want to write one
name the registers; then you would need additional conditionals. For
example, some 68000 operating systems call this register @code{%a5}.
-Eventually there may be a way of asking the compiler to choose a register
-automatically, but first we need to figure out how it should choose and
-how to enable you to guide the choice. No solution is evident.
-
Defining such a register variable does not reserve the register; it
remains available for other uses in places where flow control determines
the variable's value is not live. However, these registers are made
-unavailable for use in the reload pass. I would not be surprised if
-excessive use of this feature leaves the compiler too few available
-registers to compile certain functions.
+unavailable for use in the reload pass; excessive use of this feature
+leaves the compiler too few available registers to compile certain
+functions.
+
+This option does not guarantee that GNU CC will generate code that has
+this variable in the register you specify at all times. You may not
+code an explicit reference to this register in an @code{asm} statement
+and assume it will always refer to this variable.
+
+Stores into local register variables may be deleted when they appear to be dead
+according to dataflow analysis. References to local register variables may
+be deleted or moved or simplified.
@node Alternate Keywords
@section Alternate Keywords
#endif
@end example
-@samp{-pedantic} causes warnings for many GNU C extensions. You can
+@findex __extension__
+@samp{-pedantic} and other options cause warnings for many GNU C extensions.
+You can
prevent such warnings within one expression by writing
@code{__extension__} before the expression. @code{__extension__} has no
effect aside from this.
@node Function Names
@section Function Names as Strings
-GNU CC predefines two string variables to be the name of the current function.
-The variable @code{__FUNCTION__} is the name of the function as it appears
-in the source. The variable @code{__PRETTY_FUNCTION__} is the name of
-the function pretty printed in a language specific fashion.
+GNU CC predefines two magic identifiers to hold the name of the current
+function. The identifier @code{__FUNCTION__} holds the name of the function
+as it appears in the source. The identifier @code{__PRETTY_FUNCTION__}
+holds the name of the function pretty printed in a language specific
+fashion.
These names are always the same in a C function, but in a C++ function
they may be different. For example, this program:
__PRETTY_FUNCTION__ = int a::sub (int)
@end smallexample
-These names are not macros: they are predefined string variables.
-For example, @samp{#ifdef __FUNCTION__} does not have any special
+The compiler automagically replaces the identifiers with a string
+literal containing the appropriate name. Thus, they are neither
+preprocessor macros, like @code{__FILE__} and @code{__LINE__}, nor
+variables. This means that they catenate with other string literals, and
+that they can be used to initialize char arrays. For example
+
+@smallexample
+char here[] = "Function " __FUNCTION__ " in " __FILE__;
+@end smallexample
+
+On the other hand, @samp{#ifdef __FUNCTION__} does not have any special
meaning inside a function, since the preprocessor does not do anything
special with the identifier @code{__FUNCTION__}.
+GNU CC also supports the magic word @code{__func__}, defined by the
+draft standard for C-99:
+
+@display
+The identifier @code{__func__} is implicitly declared by the translator
+as if, immediately following the opening brace of each function
+definition, the declaration
+
+@smallexample
+static const char __func__[] = "function-name";
+@end smallexample
+
+appeared, where function-name is the name of the lexically-enclosing
+function. This name is the unadorned name of the function.
+@end display
+
+By this definition, @code{__func__} is a variable, not a string literal.
+In particular, @code{__func__} does not catenate with other string
+literals.
+
+In @code{C++}, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} are
+variables, declared in the same way as @code{__func__}.
+
@node Return Address
@section Getting the Return or Frame Address of a Function
function.
@table @code
+@findex __builtin_return_address
@item __builtin_return_address (@var{level})
This function returns the return address of the current function, or of
one of its callers. The @var{level} argument is number of frames to
This function should only be used with a non-zero argument for debugging
purposes.
+@findex __builtin_frame_address
@item __builtin_frame_address (@var{level})
This function is similar to @code{__builtin_return_address}, but it
returns the address of the function frame rather than the return address
function as well.
@end table
+@node Other Builtins
+@section Other built-in functions provided by GNU CC
+
+GNU CC provides a large number of built-in functions other than the ones
+mentioned above. Some of these are for internal use in the processing
+of exceptions or variable-length argument lists and will not be
+documented here because they may change from time to time; we do not
+recommend general use of these functions.
+
+The remaining functions are provided for optimization purposes.
+
+GNU CC includes builtin versions of many of the functions in the
+standard C library. These will always be treated as having the same
+meaning as the C library function even if you specify the
+@samp{-fno-builtin} (@pxref{C Dialect Options}) option. These functions
+correspond to the C library functions @code{abort}, @code{abs},
+@code{alloca}, @code{cos}, @code{cosf}, @code{cosl}, @code{exit},
+@code{_exit}, @code{fabs}, @code{fabsf}, @code{fabsl}, @code{ffs},
+@code{labs}, @code{memcmp}, @code{memcpy}, @code{memset}, @code{sin},
+@code{sinf}, @code{sinl}, @code{sqrt}, @code{sqrtf}, @code{sqrtl},
+@code{strcmp}, @code{strcpy}, and @code{strlen}.
+
+@findex __builtin_constant_p
+You can use the builtin function @code{__builtin_constant_p} to
+determine if a value is known to be constant at compile-time and hence
+that GNU CC can perform constant-folding on expressions involving that
+value. The argument of the function is the value to test. The function
+returns the integer 1 if the argument is known to be a compile-time
+constant and 0 if it is not known to be a compile-time constant. A
+return of 0 does not indicate that the value is @emph{not} a constant,
+but merely that GNU CC cannot prove it is a constant with the specified
+value of the @samp{-O} option.
+
+You would typically use this function in an embedded application where
+memory was a critical resource. If you have some complex calculation,
+you may want it to be folded if it involves constants, but need to call
+a function if it does not. For example:
+
+@smallexample
+#define Scale_Value(X) \
+ (__builtin_constant_p (X) ? ((X) * SCALE + OFFSET) : Scale (X))
+@end smallexample
+
+You may use this builtin function in either a macro or an inline
+function. However, if you use it in an inlined function and pass an
+argument of the function as the argument to the builtin, GNU CC will
+never return 1 when you call the inline function with a string constant
+or constructor expression (@pxref{Constructors}) and will not return 1
+when you pass a constant numeric value to the inline function unless you
+specify the @samp{-O} option.
+
+@node Deprecated Features
+@section Deprecated Features
+
+In the past, the GNU C++ compiler was extended to experiment with new
+features, at a time when the C++ language was still evolving. Now that
+the C++ standard is complete, some of those features are superseded by
+superior alternatives. Using the old features might cause a warning in
+some cases that the feature will be dropped in the future. In other
+cases, the feature might be gone already.
+
+While the list below is not exhaustive, it documents some of the options
+that are now deprecated:
+
+@table @code
+@item -fthis-is-variable
+In early versions of C++, assignment to this could be used to implement
+application-defined memory allocation. Now, allocation functions
+(@samp{operator new}) are the standard-conforming way to achieve the
+same effect.
+
+@item -fexternal-templates
+@itemx -falt-external-templates
+These are two of the many ways for g++ to implement template
+instantiation. @xref{Template Instantiation}. The C++ standard clearly
+defines how template definitions have to be organized across
+implementation units. g++ has an implicit instantiation mechanism that
+should work just fine for standard-conforming code.
+
+@end table
+
@node C++ Extensions
@chapter Extensions to the C++ Language
@cindex extensions, C++ language
@menu
* Naming Results:: Giving a name to C++ function return values.
* Min and Max:: C++ Minimum and maximum operators.
-* Destructors and Goto:: Goto is safe to use in C++ even when destructors
- are needed.
+* Volatiles:: What constitutes an access to a volatile object.
+* Restricted Pointers:: C9X restricted pointers and references.
* C++ Interface:: You can use a single C++ header file for both
declarations and definitions.
* Template Instantiation:: Methods for ensuring that exactly one copy of
each needed template instantiation is emitted.
-* C++ Signatures:: You can specify abstract types to get subtype
- polymorphism independent from inheritance.
+* Bound member functions:: You can extract a function pointer to the
+ method denoted by a @samp{->*} or @samp{.*} expression.
@end menu
@node Naming Results
handle expressions with side-effects; @w{@samp{int min = i++ <? j++;}}
works correctly.
-@node Destructors and Goto
-@section @code{goto} and Destructors in GNU C++
+@node Volatiles
+@section When is a Volatile Object Accessed?
+@cindex accessing volatiles
+@cindex volatile read
+@cindex volatile write
+@cindex volatile access
+
+Both the C and C++ standard have the concept of volatile objects. These
+are normally accessed by pointers and used for accessing hardware. The
+standards encourage compilers to refrain from optimizations on
+concerning accesses to volatile objects that it might perform on
+non-volatile objects. The C standard leaves it implementation defined
+as to what constitutes a volatile access. The C++ standard omits to
+specify this, except to say that C++ should behave in a similar manner
+to C with respect to volatiles, where possible. The minimum either
+standard specifies is that at a sequence point all previous access to
+volatile objects have stabilized and no subsequent accesses have
+occurred. Thus an implementation is free to reorder and combine
+volatile accesses which occur between sequence points, but cannot do so
+for accesses across a sequence point. The use of volatiles does not
+allow you to violate the restriction on updating objects multiple times
+within a sequence point.
+
+In most expressions, it is intuitively obvious what is a read and what is
+a write. For instance
+
+@example
+volatile int *dst = <somevalue>;
+volatile int *src = <someothervalue>;
+*dst = *src;
+@end example
+
+@noindent
+will cause a read of the volatile object pointed to by @var{src} and stores the
+value into the volatile object pointed to by @var{dst}. There is no
+guarantee that these reads and writes are atomic, especially for objects
+larger than @code{int}.
+
+Less obvious expressions are where something which looks like an access
+is used in a void context. An example would be,
+
+@example
+volatile int *src = <somevalue>;
+*src;
+@end example
+
+With C, such expressions are rvalues, and as rvalues cause a read of
+the object, gcc interprets this as a read of the volatile being pointed
+to. The C++ standard specifies that such expressions do not undergo
+lvalue to rvalue conversion, and that the type of the dereferenced
+object may be incomplete. The C++ standard does not specify explicitly
+that it is this lvalue to rvalue conversion which is responsible for
+causing an access. However, there is reason to believe that it is,
+because otherwise certain simple expressions become undefined. However,
+because it would surprise most programmers, g++ treats dereferencing a
+pointer to volatile object of complete type in a void context as a read
+of the object. When the object has incomplete type, g++ issues a
+warning.
+
+@example
+struct S;
+struct T @{int m;@};
+volatile S *ptr1 = <somevalue>;
+volatile T *ptr2 = <somevalue>;
+*ptr1;
+*ptr2;
+@end example
+
+In this example, a warning is issued for @code{*ptr1}, and @code{*ptr2}
+causes a read of the object pointed to. If you wish to force an error on
+the first case, you must force a conversion to rvalue with, for instance
+a static cast, @code{static_cast<S>(*ptr1)}.
+
+When using a reference to volatile, g++ does not treat equivalent
+expressions as accesses to volatiles, but instead issues a warning that
+no volatile is accessed. The rationale for this is that otherwise it
+becomes difficult to determine where volatile access occur, and not
+possible to ignore the return value from functions returning volatile
+references. Again, if you wish to force a read, cast the reference to
+an rvalue.
+
+@node Restricted Pointers
+@section Restricting Pointer Aliasing
+@cindex restricted pointers
+@cindex restricted references
+@cindex restricted this pointer
+
+As with gcc, g++ understands the C9X proposal of restricted pointers,
+specified with the @code{__restrict__}, or @code{__restrict} type
+qualifier. Because you cannot compile C++ by specifying the -flang-isoc9x
+language flag, @code{restrict} is not a keyword in C++.
+
+In addition to allowing restricted pointers, you can specify restricted
+references, which indicate that the reference is not aliased in the local
+context.
+
+@example
+void fn (int *__restrict__ rptr, int &__restrict__ rref)
+@{
+ @dots{}
+@}
+@end example
+
+@noindent
+In the body of @code{fn}, @var{rptr} points to an unaliased integer and
+@var{rref} refers to a (different) unaliased integer.
-@cindex @code{goto} in C++
-@cindex destructors vs @code{goto}
-In C++ programs, you can safely use the @code{goto} statement. When you
-use it to exit a block which contains aggregates requiring destructors,
-the destructors will run before the @code{goto} transfers control.
+You may also specify whether a member function's @var{this} pointer is
+unaliased by using @code{__restrict__} as a member function qualifier.
-@cindex constructors vs @code{goto}
-The compiler still forbids using @code{goto} to @emph{enter} a scope
-that requires constructors.
+@example
+void T::fn () __restrict__
+@{
+ @dots{}
+@}
+@end example
+
+@noindent
+Within the body of @code{T::fn}, @var{this} will have the effective
+definition @code{T *__restrict__ const this}. Notice that the
+interpretation of a @code{__restrict__} member function qualifier is
+different to that of @code{const} or @code{volatile} qualifier, in that it
+is applied to the pointer rather than the object. This is consistent with
+other compilers which implement restricted pointers.
+
+As with all outermost parameter qualifiers, @code{__restrict__} is
+ignored in function definition matching. This means you only need to
+specify @code{__restrict__} in a function definition, rather than
+in a function prototype as well.
@node C++ Interface
@section Declarations and Definitions in One Header
@table @asis
@item Borland model
Borland C++ solved the template instantiation problem by adding the code
-equivalent of common blocks to their linker; template instances
-are emitted in each translation unit that uses them, and they are
-collapsed together at run time. The advantage of this model is that the
-linker only has to consider the object files themselves; there is no
-external complexity to worry about. This disadvantage is that
-compilation time is increased because the template code is being
-compiled repeatedly. Code written for this model tends to include
-definitions of all member templates in the header file, since they must
-be seen to be compiled.
+equivalent of common blocks to their linker; the compiler emits template
+instances in each translation unit that uses them, and the linker
+collapses them together. The advantage of this model is that the linker
+only has to consider the object files themselves; there is no external
+complexity to worry about. This disadvantage is that compilation time
+is increased because the template code is being compiled repeatedly.
+Code written for this model tends to include definitions of all
+templates in the header file, since they must be seen to be
+instantiated.
@item Cfront model
The AT&T C++ translator, Cfront, solved the template instantiation
problem by creating the notion of a template repository, an
-automatically maintained place where template instances are stored. As
-individual object files are built, notes are placed in the repository to
-record where templates and potential type arguments were seen so that
-the subsequent instantiation step knows where to find them. At link
-time, any needed instances are generated and linked in. The advantages
-of this model are more optimal compilation speed and the ability to use
-the system linker; to implement the Borland model a compiler vendor also
+automatically maintained place where template instances are stored. A
+more modern version of the repository works as follows: As individual
+object files are built, the compiler places any template definitions and
+instantiations encountered in the repository. At link time, the link
+wrapper adds in the objects in the repository and compiles any needed
+instances that were not previously emitted. The advantages of this
+model are more optimal compilation speed and the ability to use the
+system linker; to implement the Borland model a compiler vendor also
needs to replace the linker. The disadvantages are vastly increased
-complexity, and thus potential for error; theoretically, this should be
-just as transparent, but in practice it has been very difficult to build
+complexity, and thus potential for error; for some code this can be
+just as transparent, but in practice it can been very difficult to build
multiple programs in one directory and one program in multiple
-directories using Cfront. Code written for this model tends to separate
-definitions of non-inline member templates into a separate file, which
-is magically found by the link preprocessor when a template needs to be
-instantiated.
+directories. Code written for this model tends to separate definitions
+of non-inline member templates into a separate file, which should be
+compiled separately.
@end table
-Currently, g++ implements neither automatic model. In the mean time,
-you have three options for dealing with template instantiations:
+When used with GNU ld version 2.8 or later on an ELF system such as
+Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the
+Borland model. On other systems, g++ implements neither automatic
+model.
+
+A future version of g++ will support a hybrid model whereby the compiler
+will emit any instantiations for which the template definition is
+included in the compile, and store template definitions and
+instantiation context information into the object file for the rest.
+The link wrapper will extract that information as necessary and invoke
+the compiler to produce the remaining instantiations. The linker will
+then combine duplicate instantiations.
+
+In the mean time, you have the following options for dealing with
+template instantiations:
@enumerate
@item
+Compile your template-using code with @samp{-frepo}. The compiler will
+generate files with the extension @samp{.rpo} listing all of the
+template instantiations used in the corresponding object files which
+could be instantiated there; the link wrapper, @samp{collect2}, will
+then update the @samp{.rpo} files to tell the compiler where to place
+those instantiations and rebuild any affected object files. The
+link-time overhead is negligible after the first pass, as the compiler
+will continue to place the instantiations in the same files.
+
+This is your best option for application code written for the Borland
+model, as it will just work. Code written for the Cfront model will
+need to be modified so that the template definitions are available at
+one or more points of instantiation; usually this is as simple as adding
+@code{#include <tmethods.cc>} to the end of each template header.
+
+For library code, if you want the library to provide all of the template
+instantiations it needs, just try to link all of its object files
+together; the link will fail, but cause the instantiations to be
+generated as a side effect. Be warned, however, that this may cause
+conflicts if multiple libraries try to provide the same instantiations.
+For greater control, use explicit instantiation as described in the next
+option.
+
+@item
Compile your code with @samp{-fno-implicit-templates} to disable the
implicit generation of template instances, and explicitly instantiate
all the ones you use. This approach requires more knowledge of exactly
other files) without having to specify them as well.
g++ has extended the template instantiation syntax outlined in the
-Working Paper to allow forward declaration of explicit instantiations,
-explicit instantiation of members of template classes and instantiation
-of the compiler support data for a template class (i.e. the vtable)
-without instantiating any of its members:
+Working Paper to allow forward declaration of explicit instantiations
+and instantiation of the compiler support data for a template class
+(i.e. the vtable) without instantiating any of its members:
@example
extern template int max (int, int);
-template void Foo<int>::f ();
inline template class Foo<int>;
@end example
more discussion of these pragmas.
@end enumerate
-@node C++ Signatures
-@section Type Abstraction using Signatures
-
-@findex signature
-@cindex type abstraction, C++
-@cindex C++ type abstraction
-@cindex subtype polymorphism, C++
-@cindex C++ subtype polymorphism
-@cindex signatures, C++
-@cindex C++ signatures
-
-In GNU C++, you can use the keyword @code{signature} to define a
-completely abstract class interface as a datatype. You can connect this
-abstraction with actual classes using signature pointers. If you want
-to use signatures, run the GNU compiler with the
-@samp{-fhandle-signatures} command-line option. (With this option, the
-compiler reserves a second keyword @code{sigof} as well, for a future
-extension.)
-
-Roughly, signatures are type abstractions or interfaces of classes.
-Some other languages have similar facilities. C++ signatures are
-related to ML's signatures, Haskell's type classes, definition modules
-in Modula-2, interface modules in Modula-3, abstract types in Emerald,
-type modules in Trellis/Owl, categories in Scratchpad II, and types in
-POOL-I. For a more detailed discussion of signatures, see
-@cite{Signatures: A Language Extension for Improving Type Abstraction and
-Subtype Polymorphism in C++}
-by @w{Gerald} Baumgartner and Vincent F. Russo (Tech report
-CSD--TR--95--051, Dept. of Computer Sciences, Purdue University,
-August 1995, a slightly improved version appeared in
-@emph{Software---Practice & Experience}, @b{25}(8), pp. 863--889,
-August 1995). You can get the tech report by anonymous FTP from
-@code{ftp.cs.purdue.edu} in @file{pub/gb/Signature-design.ps.gz}.
-
-Syntactically, a signature declaration is a collection of
-member function declarations and nested type declarations.
-For example, this signature declaration defines a new abstract type
-@code{S} with member functions @samp{int foo ()} and @samp{int bar (int)}:
-
-@example
-signature S
-@{
- int foo ();
- int bar (int);
-@};
-@end example
-
-Since signature types do not include implementation definitions, you
-cannot write an instance of a signature directly. Instead, you can
-define a pointer to any class that contains the required interfaces as a
-@dfn{signature pointer}. Such a class @dfn{implements} the signature
-type.
-@c Eventually signature references should work too.
+@node Bound member functions
+@section Extracting the function pointer from a bound pointer to member function
-To use a class as an implementation of @code{S}, you must ensure that
-the class has public member functions @samp{int foo ()} and @samp{int
-bar (int)}. The class can have other member functions as well, public
-or not; as long as it offers what's declared in the signature, it is
-suitable as an implementation of that signature type.
+@cindex pmf
+@cindex pointer to member function
+@cindex bound pointer to member function
-For example, suppose that @code{C} is a class that meets the
-requirements of signature @code{S} (@code{C} @dfn{conforms to}
-@code{S}). Then
-
-@example
-C obj;
-S * p = &obj;
-@end example
+In C++, pointer to member functions (PMFs) are implemented using a wide
+pointer of sorts to handle all the possible call mechanisms; the PMF
+needs to store information about how to adjust the @samp{this} pointer,
+and if the function pointed to is virtual, where to find the vtable, and
+where in the vtable to look for the member function. If you are using
+PMFs in an inner loop, you should really reconsider that decision. If
+that is not an option, you can extract the pointer to the function that
+would be called for a given object/PMF pair and call it directly inside
+the inner loop, to save a bit of time.
-@noindent
-defines a signature pointer @code{p} and initializes it to point to an
-object of type @code{C}.
-The member function call @w{@samp{int i = p->foo ();}}
-executes @samp{obj.foo ()}.
+Note that you will still be paying the penalty for the call through a
+function pointer; on most modern architectures, such a call defeats the
+branch prediction features of the CPU. This is also true of normal
+virtual function calls.
-@cindex @code{signature} in C++, advantages
-Abstract virtual classes provide somewhat similar facilities in standard
-C++. There are two main advantages to using signatures instead:
+The syntax for this extension is
-@enumerate
-@item
-Subtyping becomes independent from inheritance. A class or signature
-type @code{T} is a subtype of a signature type @code{S} independent of
-any inheritance hierarchy as long as all the member functions declared
-in @code{S} are also found in @code{T}. So you can define a subtype
-hierarchy that is completely independent from any inheritance
-(implementation) hierarchy, instead of being forced to use types that
-mirror the class inheritance hierarchy.
+@example
+extern A a;
+extern int (A::*fp)();
+typedef int (*fptr)(A *);
-@item
-Signatures allow you to work with existing class hierarchies as
-implementations of a signature type. If those class hierarchies are
-only available in compiled form, you're out of luck with abstract virtual
-classes, since an abstract virtual class cannot be retrofitted on top of
-existing class hierarchies. So you would be required to write interface
-classes as subtypes of the abstract virtual class.
-@end enumerate
+fptr p = (fptr)(a.*fp);
+@end example
-@cindex default implementation, signature member function
-@cindex signature member function default implementation
-There is one more detail about signatures. A signature declaration can
-contain member function @emph{definitions} as well as member function
-declarations. A signature member function with a full definition is
-called a @emph{default implementation}; classes need not contain that
-particular interface in order to conform. For example, a
-class @code{C} can conform to the signature
+For PMF constants (i.e. expressions of the form @samp{&Klasse::Member}),
+no object is needed to obtain the address of the function. They can be
+converted to function pointers directly:
@example
-signature T
-@{
- int f (int);
- int f0 () @{ return f (0); @};
-@};
+fptr p1 = (fptr)(&A::foo);
@end example
-@noindent
-whether or not @code{C} implements the member function @samp{int f0 ()}.
-If you define @code{C::f0}, that definition takes precedence;
-otherwise, the default implementation @code{S::f0} applies.
-
-@ignore
-There will be more support for signatures in the future.
-Add to this doc as the implementation grows.
-In particular, the following features are planned but not yet
-implemented:
-@itemize @bullet
-@item signature references,
-@item signature inheritance,
-@item the @code{sigof} construct for extracting the signature information
- of a class,
-@item views for renaming member functions when matching a class type
- with a signature type,
-@item specifying exceptions with signature member functions, and
-@item signature templates.
-@end itemize
-This list is roughly in the order in which we intend to implement
-them. Watch this space for updates.
-@end ignore
+You must specify @samp{-Wno-pmf-conversions} to use this extension.
+
OSDN Git Service
