1 | This is Info file gcc.info, produced by Makeinfo version 1.67 from the |
---|
2 | input file gcc.texi. |
---|
3 | |
---|
4 | This file documents the use and the internals of the GNU compiler. |
---|
5 | |
---|
6 | Published by the Free Software Foundation 59 Temple Place - Suite 330 |
---|
7 | Boston, MA 02111-1307 USA |
---|
8 | |
---|
9 | Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998 |
---|
10 | Free Software Foundation, Inc. |
---|
11 | |
---|
12 | Permission is granted to make and distribute verbatim copies of this |
---|
13 | manual provided the copyright notice and this permission notice are |
---|
14 | preserved on all copies. |
---|
15 | |
---|
16 | Permission is granted to copy and distribute modified versions of |
---|
17 | this manual under the conditions for verbatim copying, provided also |
---|
18 | that the sections entitled "GNU General Public License," "Funding for |
---|
19 | Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are |
---|
20 | included exactly as in the original, and provided that the entire |
---|
21 | resulting derived work is distributed under the terms of a permission |
---|
22 | notice identical to this one. |
---|
23 | |
---|
24 | Permission is granted to copy and distribute translations of this |
---|
25 | manual into another language, under the above conditions for modified |
---|
26 | versions, except that the sections entitled "GNU General Public |
---|
27 | License," "Funding for Free Software," and "Protect Your Freedom--Fight |
---|
28 | `Look And Feel'", and this permission notice, may be included in |
---|
29 | translations approved by the Free Software Foundation instead of in the |
---|
30 | original English. |
---|
31 | |
---|
32 | |
---|
33 | File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions |
---|
34 | |
---|
35 | An Inline Function is As Fast As a Macro |
---|
36 | ======================================== |
---|
37 | |
---|
38 | By declaring a function `inline', you can direct GNU CC to integrate |
---|
39 | that function's code into the code for its callers. This makes |
---|
40 | execution faster by eliminating the function-call overhead; in |
---|
41 | addition, if any of the actual argument values are constant, their known |
---|
42 | values may permit simplifications at compile time so that not all of the |
---|
43 | inline function's code needs to be included. The effect on code size is |
---|
44 | less predictable; object code may be larger or smaller with function |
---|
45 | inlining, depending on the particular case. Inlining of functions is an |
---|
46 | optimization and it really "works" only in optimizing compilation. If |
---|
47 | you don't use `-O', no function is really inline. |
---|
48 | |
---|
49 | To declare a function inline, use the `inline' keyword in its |
---|
50 | declaration, like this: |
---|
51 | |
---|
52 | inline int |
---|
53 | inc (int *a) |
---|
54 | { |
---|
55 | (*a)++; |
---|
56 | } |
---|
57 | |
---|
58 | (If you are writing a header file to be included in ANSI C programs, |
---|
59 | write `__inline__' instead of `inline'. *Note Alternate Keywords::.) |
---|
60 | |
---|
61 | You can also make all "simple enough" functions inline with the |
---|
62 | option `-finline-functions'. Note that certain usages in a function |
---|
63 | definition can make it unsuitable for inline substitution. |
---|
64 | |
---|
65 | Note that in C and Objective C, unlike C++, the `inline' keyword |
---|
66 | does not affect the linkage of the function. |
---|
67 | |
---|
68 | GNU CC automatically inlines member functions defined within the |
---|
69 | class body of C++ programs even if they are not explicitly declared |
---|
70 | `inline'. (You can override this with `-fno-default-inline'; *note |
---|
71 | Options Controlling C++ Dialect: C++ Dialect Options..) |
---|
72 | |
---|
73 | When a function is both inline and `static', if all calls to the |
---|
74 | function are integrated into the caller, and the function's address is |
---|
75 | never used, then the function's own assembler code is never referenced. |
---|
76 | In this case, GNU CC does not actually output assembler code for the |
---|
77 | function, unless you specify the option `-fkeep-inline-functions'. |
---|
78 | Some calls cannot be integrated for various reasons (in particular, |
---|
79 | calls that precede the function's definition cannot be integrated, and |
---|
80 | neither can recursive calls within the definition). If there is a |
---|
81 | nonintegrated call, then the function is compiled to assembler code as |
---|
82 | usual. The function must also be compiled as usual if the program |
---|
83 | refers to its address, because that can't be inlined. |
---|
84 | |
---|
85 | When an inline function is not `static', then the compiler must |
---|
86 | assume that there may be calls from other source files; since a global |
---|
87 | symbol can be defined only once in any program, the function must not |
---|
88 | be defined in the other source files, so the calls therein cannot be |
---|
89 | integrated. Therefore, a non-`static' inline function is always |
---|
90 | compiled on its own in the usual fashion. |
---|
91 | |
---|
92 | If you specify both `inline' and `extern' in the function |
---|
93 | definition, then the definition is used only for inlining. In no case |
---|
94 | is the function compiled on its own, not even if you refer to its |
---|
95 | address explicitly. Such an address becomes an external reference, as |
---|
96 | if you had only declared the function, and had not defined it. |
---|
97 | |
---|
98 | This combination of `inline' and `extern' has almost the effect of a |
---|
99 | macro. The way to use it is to put a function definition in a header |
---|
100 | file with these keywords, and put another copy of the definition |
---|
101 | (lacking `inline' and `extern') in a library file. The definition in |
---|
102 | the header file will cause most calls to the function to be inlined. |
---|
103 | If any uses of the function remain, they will refer to the single copy |
---|
104 | in the library. |
---|
105 | |
---|
106 | GNU C does not inline any functions when not optimizing. It is not |
---|
107 | clear whether it is better to inline or not, in this case, but we found |
---|
108 | that a correct implementation when not optimizing was difficult. So we |
---|
109 | did the easy thing, and turned it off. |
---|
110 | |
---|
111 | |
---|
112 | File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: C Extensions |
---|
113 | |
---|
114 | Assembler Instructions with C Expression Operands |
---|
115 | ================================================= |
---|
116 | |
---|
117 | In an assembler instruction using `asm', you can specify the |
---|
118 | operands of the instruction using C expressions. This means you need |
---|
119 | not guess which registers or memory locations will contain the data you |
---|
120 | want to use. |
---|
121 | |
---|
122 | You must specify an assembler instruction template much like what |
---|
123 | appears in a machine description, plus an operand constraint string for |
---|
124 | each operand. |
---|
125 | |
---|
126 | For example, here is how to use the 68881's `fsinx' instruction: |
---|
127 | |
---|
128 | asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); |
---|
129 | |
---|
130 | Here `angle' is the C expression for the input operand while `result' |
---|
131 | is that of the output operand. Each has `"f"' as its operand |
---|
132 | constraint, saying that a floating point register is required. The `=' |
---|
133 | in `=f' indicates that the operand is an output; all output operands' |
---|
134 | constraints must use `='. The constraints use the same language used |
---|
135 | in the machine description (*note Constraints::.). |
---|
136 | |
---|
137 | Each operand is described by an operand-constraint string followed by |
---|
138 | the C expression in parentheses. A colon separates the assembler |
---|
139 | template from the first output operand and another separates the last |
---|
140 | output operand from the first input, if any. Commas separate the |
---|
141 | operands within each group. The total number of operands is limited to |
---|
142 | ten or to the maximum number of operands in any instruction pattern in |
---|
143 | the machine description, whichever is greater. |
---|
144 | |
---|
145 | If there are no output operands but there are input operands, you |
---|
146 | must place two consecutive colons surrounding the place where the output |
---|
147 | operands would go. |
---|
148 | |
---|
149 | Output operand expressions must be lvalues; the compiler can check |
---|
150 | this. The input operands need not be lvalues. The compiler cannot |
---|
151 | check whether the operands have data types that are reasonable for the |
---|
152 | instruction being executed. It does not parse the assembler instruction |
---|
153 | template and does not know what it means or even whether it is valid |
---|
154 | assembler input. The extended `asm' feature is most often used for |
---|
155 | machine instructions the compiler itself does not know exist. If the |
---|
156 | output expression cannot be directly addressed (for example, it is a |
---|
157 | bit field), your constraint must allow a register. In that case, GNU CC |
---|
158 | will use the register as the output of the `asm', and then store that |
---|
159 | register into the output. |
---|
160 | |
---|
161 | The ordinary output operands must be write-only; GNU CC will assume |
---|
162 | that the values in these operands before the instruction are dead and |
---|
163 | need not be generated. Extended asm supports input-output or read-write |
---|
164 | operands. Use the constraint character `+' to indicate such an operand |
---|
165 | and list it with the output operands. |
---|
166 | |
---|
167 | When the constraints for the read-write operand (or the operand in |
---|
168 | which only some of the bits are to be changed) allows a register, you |
---|
169 | may, as an alternative, logically split its function into two separate |
---|
170 | operands, one input operand and one write-only output operand. The |
---|
171 | connection between them is expressed by constraints which say they need |
---|
172 | to be in the same location when the instruction executes. You can use |
---|
173 | the same C expression for both operands, or different expressions. For |
---|
174 | example, here we write the (fictitious) `combine' instruction with |
---|
175 | `bar' as its read-only source operand and `foo' as its read-write |
---|
176 | destination: |
---|
177 | |
---|
178 | asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); |
---|
179 | |
---|
180 | The constraint `"0"' for operand 1 says that it must occupy the same |
---|
181 | location as operand 0. A digit in constraint is allowed only in an |
---|
182 | input operand and it must refer to an output operand. |
---|
183 | |
---|
184 | Only a digit in the constraint can guarantee that one operand will |
---|
185 | be in the same place as another. The mere fact that `foo' is the value |
---|
186 | of both operands is not enough to guarantee that they will be in the |
---|
187 | same place in the generated assembler code. The following would not |
---|
188 | work reliably: |
---|
189 | |
---|
190 | asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); |
---|
191 | |
---|
192 | Various optimizations or reloading could cause operands 0 and 1 to |
---|
193 | be in different registers; GNU CC knows no reason not to do so. For |
---|
194 | example, the compiler might find a copy of the value of `foo' in one |
---|
195 | register and use it for operand 1, but generate the output operand 0 in |
---|
196 | a different register (copying it afterward to `foo''s own address). Of |
---|
197 | course, since the register for operand 1 is not even mentioned in the |
---|
198 | assembler code, the result will not work, but GNU CC can't tell that. |
---|
199 | |
---|
200 | Some instructions clobber specific hard registers. To describe this, |
---|
201 | write a third colon after the input operands, followed by the names of |
---|
202 | the clobbered hard registers (given as strings). Here is a realistic |
---|
203 | example for the VAX: |
---|
204 | |
---|
205 | asm volatile ("movc3 %0,%1,%2" |
---|
206 | : /* no outputs */ |
---|
207 | : "g" (from), "g" (to), "g" (count) |
---|
208 | : "r0", "r1", "r2", "r3", "r4", "r5"); |
---|
209 | |
---|
210 | If you refer to a particular hardware register from the assembler |
---|
211 | code, you will probably have to list the register after the third colon |
---|
212 | to tell the compiler the register's value is modified. In some |
---|
213 | assemblers, the register names begin with `%'; to produce one `%' in the |
---|
214 | assembler code, you must write `%%' in the input. |
---|
215 | |
---|
216 | If your assembler instruction can alter the condition code register, |
---|
217 | add `cc' to the list of clobbered registers. GNU CC on some machines |
---|
218 | represents the condition codes as a specific hardware register; `cc' |
---|
219 | serves to name this register. On other machines, the condition code is |
---|
220 | handled differently, and specifying `cc' has no effect. But it is |
---|
221 | valid no matter what the machine. |
---|
222 | |
---|
223 | If your assembler instruction modifies memory in an unpredictable |
---|
224 | fashion, add `memory' to the list of clobbered registers. This will |
---|
225 | cause GNU CC to not keep memory values cached in registers across the |
---|
226 | assembler instruction. |
---|
227 | |
---|
228 | You can put multiple assembler instructions together in a single |
---|
229 | `asm' template, separated either with newlines (written as `\n') or |
---|
230 | with semicolons if the assembler allows such semicolons. The GNU |
---|
231 | assembler allows semicolons and most Unix assemblers seem to do so. |
---|
232 | The input operands are guaranteed not to use any of the clobbered |
---|
233 | registers, and neither will the output operands' addresses, so you can |
---|
234 | read and write the clobbered registers as many times as you like. Here |
---|
235 | is an example of multiple instructions in a template; it assumes the |
---|
236 | subroutine `_foo' accepts arguments in registers 9 and 10: |
---|
237 | |
---|
238 | asm ("movl %0,r9;movl %1,r10;call _foo" |
---|
239 | : /* no outputs */ |
---|
240 | : "g" (from), "g" (to) |
---|
241 | : "r9", "r10"); |
---|
242 | |
---|
243 | Unless an output operand has the `&' constraint modifier, GNU CC may |
---|
244 | allocate it in the same register as an unrelated input operand, on the |
---|
245 | assumption the inputs are consumed before the outputs are produced. |
---|
246 | This assumption may be false if the assembler code actually consists of |
---|
247 | more than one instruction. In such a case, use `&' for each output |
---|
248 | operand that may not overlap an input. *Note Modifiers::. |
---|
249 | |
---|
250 | If you want to test the condition code produced by an assembler |
---|
251 | instruction, you must include a branch and a label in the `asm' |
---|
252 | construct, as follows: |
---|
253 | |
---|
254 | asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:" |
---|
255 | : "g" (result) |
---|
256 | : "g" (input)); |
---|
257 | |
---|
258 | This assumes your assembler supports local labels, as the GNU assembler |
---|
259 | and most Unix assemblers do. |
---|
260 | |
---|
261 | Speaking of labels, jumps from one `asm' to another are not |
---|
262 | supported. The compiler's optimizers do not know about these jumps, and |
---|
263 | therefore they cannot take account of them when deciding how to |
---|
264 | optimize. |
---|
265 | |
---|
266 | Usually the most convenient way to use these `asm' instructions is to |
---|
267 | encapsulate them in macros that look like functions. For example, |
---|
268 | |
---|
269 | #define sin(x) \ |
---|
270 | ({ double __value, __arg = (x); \ |
---|
271 | asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ |
---|
272 | __value; }) |
---|
273 | |
---|
274 | Here the variable `__arg' is used to make sure that the instruction |
---|
275 | operates on a proper `double' value, and to accept only those arguments |
---|
276 | `x' which can convert automatically to a `double'. |
---|
277 | |
---|
278 | Another way to make sure the instruction operates on the correct data |
---|
279 | type is to use a cast in the `asm'. This is different from using a |
---|
280 | variable `__arg' in that it converts more different types. For |
---|
281 | example, if the desired type were `int', casting the argument to `int' |
---|
282 | would accept a pointer with no complaint, while assigning the argument |
---|
283 | to an `int' variable named `__arg' would warn about using a pointer |
---|
284 | unless the caller explicitly casts it. |
---|
285 | |
---|
286 | If an `asm' has output operands, GNU CC assumes for optimization |
---|
287 | purposes the instruction has no side effects except to change the output |
---|
288 | operands. This does not mean instructions with a side effect cannot be |
---|
289 | used, but you must be careful, because the compiler may eliminate them |
---|
290 | if the output operands aren't used, or move them out of loops, or |
---|
291 | replace two with one if they constitute a common subexpression. Also, |
---|
292 | if your instruction does have a side effect on a variable that otherwise |
---|
293 | appears not to change, the old value of the variable may be reused later |
---|
294 | if it happens to be found in a register. |
---|
295 | |
---|
296 | You can prevent an `asm' instruction from being deleted, moved |
---|
297 | significantly, or combined, by writing the keyword `volatile' after the |
---|
298 | `asm'. For example: |
---|
299 | |
---|
300 | #define get_and_set_priority(new) \ |
---|
301 | ({ int __old; \ |
---|
302 | asm volatile ("get_and_set_priority %0, %1": "=g" (__old) : "g" (new)); \ |
---|
303 | __old; }) |
---|
304 | b |
---|
305 | |
---|
306 | If you write an `asm' instruction with no outputs, GNU CC will know the |
---|
307 | instruction has side-effects and will not delete the instruction or |
---|
308 | move it outside of loops. If the side-effects of your instruction are |
---|
309 | not purely external, but will affect variables in your program in ways |
---|
310 | other than reading the inputs and clobbering the specified registers or |
---|
311 | memory, you should write the `volatile' keyword to prevent future |
---|
312 | versions of GNU CC from moving the instruction around within a core |
---|
313 | region. |
---|
314 | |
---|
315 | An `asm' instruction without any operands or clobbers (and "old |
---|
316 | style" `asm') will not be deleted or moved significantly, regardless, |
---|
317 | unless it is unreachable, the same wasy as if you had written a |
---|
318 | `volatile' keyword. |
---|
319 | |
---|
320 | Note that even a volatile `asm' instruction can be moved in ways |
---|
321 | that appear insignificant to the compiler, such as across jump |
---|
322 | instructions. You can't expect a sequence of volatile `asm' |
---|
323 | instructions to remain perfectly consecutive. If you want consecutive |
---|
324 | output, use a single `asm'. |
---|
325 | |
---|
326 | It is a natural idea to look for a way to give access to the |
---|
327 | condition code left by the assembler instruction. However, when we |
---|
328 | attempted to implement this, we found no way to make it work reliably. |
---|
329 | The problem is that output operands might need reloading, which would |
---|
330 | result in additional following "store" instructions. On most machines, |
---|
331 | these instructions would alter the condition code before there was time |
---|
332 | to test it. This problem doesn't arise for ordinary "test" and |
---|
333 | "compare" instructions because they don't have any output operands. |
---|
334 | |
---|
335 | If you are writing a header file that should be includable in ANSI C |
---|
336 | programs, write `__asm__' instead of `asm'. *Note Alternate Keywords::. |
---|
337 | |
---|
338 | |
---|
339 | File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: C Extensions |
---|
340 | |
---|
341 | Controlling Names Used in Assembler Code |
---|
342 | ======================================== |
---|
343 | |
---|
344 | You can specify the name to be used in the assembler code for a C |
---|
345 | function or variable by writing the `asm' (or `__asm__') keyword after |
---|
346 | the declarator as follows: |
---|
347 | |
---|
348 | int foo asm ("myfoo") = 2; |
---|
349 | |
---|
350 | This specifies that the name to be used for the variable `foo' in the |
---|
351 | assembler code should be `myfoo' rather than the usual `_foo'. |
---|
352 | |
---|
353 | On systems where an underscore is normally prepended to the name of |
---|
354 | a C function or variable, this feature allows you to define names for |
---|
355 | the linker that do not start with an underscore. |
---|
356 | |
---|
357 | You cannot use `asm' in this way in a function *definition*; but you |
---|
358 | can get the same effect by writing a declaration for the function |
---|
359 | before its definition and putting `asm' there, like this: |
---|
360 | |
---|
361 | extern func () asm ("FUNC"); |
---|
362 | |
---|
363 | func (x, y) |
---|
364 | int x, y; |
---|
365 | ... |
---|
366 | |
---|
367 | It is up to you to make sure that the assembler names you choose do |
---|
368 | not conflict with any other assembler symbols. Also, you must not use a |
---|
369 | register name; that would produce completely invalid assembler code. |
---|
370 | GNU CC does not as yet have the ability to store static variables in |
---|
371 | registers. Perhaps that will be added. |
---|
372 | |
---|
373 | |
---|
374 | File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions |
---|
375 | |
---|
376 | Variables in Specified Registers |
---|
377 | ================================ |
---|
378 | |
---|
379 | GNU C allows you to put a few global variables into specified |
---|
380 | hardware registers. You can also specify the register in which an |
---|
381 | ordinary register variable should be allocated. |
---|
382 | |
---|
383 | * Global register variables reserve registers throughout the program. |
---|
384 | This may be useful in programs such as programming language |
---|
385 | interpreters which have a couple of global variables that are |
---|
386 | accessed very often. |
---|
387 | |
---|
388 | * Local register variables in specific registers do not reserve the |
---|
389 | registers. The compiler's data flow analysis is capable of |
---|
390 | determining where the specified registers contain live values, and |
---|
391 | where they are available for other uses. |
---|
392 | |
---|
393 | These local variables are sometimes convenient for use with the |
---|
394 | extended `asm' feature (*note Extended Asm::.), if you want to |
---|
395 | write one output of the assembler instruction directly into a |
---|
396 | particular register. (This will work provided the register you |
---|
397 | specify fits the constraints specified for that operand in the |
---|
398 | `asm'.) |
---|
399 | |
---|
400 | * Menu: |
---|
401 | |
---|
402 | * Global Reg Vars:: |
---|
403 | * Local Reg Vars:: |
---|
404 | |
---|
405 | |
---|
406 | File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars |
---|
407 | |
---|
408 | Defining Global Register Variables |
---|
409 | ---------------------------------- |
---|
410 | |
---|
411 | You can define a global register variable in GNU C like this: |
---|
412 | |
---|
413 | register int *foo asm ("a5"); |
---|
414 | |
---|
415 | Here `a5' is the name of the register which should be used. Choose a |
---|
416 | register which is normally saved and restored by function calls on your |
---|
417 | machine, so that library routines will not clobber it. |
---|
418 | |
---|
419 | Naturally the register name is cpu-dependent, so you would need to |
---|
420 | conditionalize your program according to cpu type. The register `a5' |
---|
421 | would be a good choice on a 68000 for a variable of pointer type. On |
---|
422 | machines with register windows, be sure to choose a "global" register |
---|
423 | that is not affected magically by the function call mechanism. |
---|
424 | |
---|
425 | In addition, operating systems on one type of cpu may differ in how |
---|
426 | they name the registers; then you would need additional conditionals. |
---|
427 | For example, some 68000 operating systems call this register `%a5'. |
---|
428 | |
---|
429 | Eventually there may be a way of asking the compiler to choose a |
---|
430 | register automatically, but first we need to figure out how it should |
---|
431 | choose and how to enable you to guide the choice. No solution is |
---|
432 | evident. |
---|
433 | |
---|
434 | Defining a global register variable in a certain register reserves |
---|
435 | that register entirely for this use, at least within the current |
---|
436 | compilation. The register will not be allocated for any other purpose |
---|
437 | in the functions in the current compilation. The register will not be |
---|
438 | saved and restored by these functions. Stores into this register are |
---|
439 | never deleted even if they would appear to be dead, but references may |
---|
440 | be deleted or moved or simplified. |
---|
441 | |
---|
442 | It is not safe to access the global register variables from signal |
---|
443 | handlers, or from more than one thread of control, because the system |
---|
444 | library routines may temporarily use the register for other things |
---|
445 | (unless you recompile them specially for the task at hand). |
---|
446 | |
---|
447 | It is not safe for one function that uses a global register variable |
---|
448 | to call another such function `foo' by way of a third function `lose' |
---|
449 | that was compiled without knowledge of this variable (i.e. in a |
---|
450 | different source file in which the variable wasn't declared). This is |
---|
451 | because `lose' might save the register and put some other value there. |
---|
452 | For example, you can't expect a global register variable to be |
---|
453 | available in the comparison-function that you pass to `qsort', since |
---|
454 | `qsort' might have put something else in that register. (If you are |
---|
455 | prepared to recompile `qsort' with the same global register variable, |
---|
456 | you can solve this problem.) |
---|
457 | |
---|
458 | If you want to recompile `qsort' or other source files which do not |
---|
459 | actually use your global register variable, so that they will not use |
---|
460 | that register for any other purpose, then it suffices to specify the |
---|
461 | compiler option `-ffixed-REG'. You need not actually add a global |
---|
462 | register declaration to their source code. |
---|
463 | |
---|
464 | A function which can alter the value of a global register variable |
---|
465 | cannot safely be called from a function compiled without this variable, |
---|
466 | because it could clobber the value the caller expects to find there on |
---|
467 | return. Therefore, the function which is the entry point into the part |
---|
468 | of the program that uses the global register variable must explicitly |
---|
469 | save and restore the value which belongs to its caller. |
---|
470 | |
---|
471 | On most machines, `longjmp' will restore to each global register |
---|
472 | variable the value it had at the time of the `setjmp'. On some |
---|
473 | machines, however, `longjmp' will not change the value of global |
---|
474 | register variables. To be portable, the function that called `setjmp' |
---|
475 | should make other arrangements to save the values of the global register |
---|
476 | variables, and to restore them in a `longjmp'. This way, the same |
---|
477 | thing will happen regardless of what `longjmp' does. |
---|
478 | |
---|
479 | All global register variable declarations must precede all function |
---|
480 | definitions. If such a declaration could appear after function |
---|
481 | definitions, the declaration would be too late to prevent the register |
---|
482 | from being used for other purposes in the preceding functions. |
---|
483 | |
---|
484 | Global register variables may not have initial values, because an |
---|
485 | executable file has no means to supply initial contents for a register. |
---|
486 | |
---|
487 | On the Sparc, there are reports that g3 ... g7 are suitable |
---|
488 | registers, but certain library functions, such as `getwd', as well as |
---|
489 | the subroutines for division and remainder, modify g3 and g4. g1 and |
---|
490 | g2 are local temporaries. |
---|
491 | |
---|
492 | On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of |
---|
493 | course, it will not do to use more than a few of those. |
---|
494 | |
---|
495 | |
---|
496 | File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars |
---|
497 | |
---|
498 | Specifying Registers for Local Variables |
---|
499 | ---------------------------------------- |
---|
500 | |
---|
501 | You can define a local register variable with a specified register |
---|
502 | like this: |
---|
503 | |
---|
504 | register int *foo asm ("a5"); |
---|
505 | |
---|
506 | Here `a5' is the name of the register which should be used. Note that |
---|
507 | this is the same syntax used for defining global register variables, |
---|
508 | but for a local variable it would appear within a function. |
---|
509 | |
---|
510 | Naturally the register name is cpu-dependent, but this is not a |
---|
511 | problem, since specific registers are most often useful with explicit |
---|
512 | assembler instructions (*note Extended Asm::.). Both of these things |
---|
513 | generally require that you conditionalize your program according to cpu |
---|
514 | type. |
---|
515 | |
---|
516 | In addition, operating systems on one type of cpu may differ in how |
---|
517 | they name the registers; then you would need additional conditionals. |
---|
518 | For example, some 68000 operating systems call this register `%a5'. |
---|
519 | |
---|
520 | Defining such a register variable does not reserve the register; it |
---|
521 | remains available for other uses in places where flow control determines |
---|
522 | the variable's value is not live. However, these registers are made |
---|
523 | unavailable for use in the reload pass; excessive use of this feature |
---|
524 | leaves the compiler too few available registers to compile certain |
---|
525 | functions. |
---|
526 | |
---|
527 | This option does not guarantee that GNU CC will generate code that |
---|
528 | has this variable in the register you specify at all times. You may not |
---|
529 | code an explicit reference to this register in an `asm' statement and |
---|
530 | assume it will always refer to this variable. |
---|
531 | |
---|
532 | |
---|
533 | File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions |
---|
534 | |
---|
535 | Alternate Keywords |
---|
536 | ================== |
---|
537 | |
---|
538 | The option `-traditional' disables certain keywords; `-ansi' |
---|
539 | disables certain others. This causes trouble when you want to use GNU C |
---|
540 | extensions, or ANSI C features, in a general-purpose header file that |
---|
541 | should be usable by all programs, including ANSI C programs and |
---|
542 | traditional ones. The keywords `asm', `typeof' and `inline' cannot be |
---|
543 | used since they won't work in a program compiled with `-ansi', while |
---|
544 | the keywords `const', `volatile', `signed', `typeof' and `inline' won't |
---|
545 | work in a program compiled with `-traditional'. |
---|
546 | |
---|
547 | The way to solve these problems is to put `__' at the beginning and |
---|
548 | end of each problematical keyword. For example, use `__asm__' instead |
---|
549 | of `asm', `__const__' instead of `const', and `__inline__' instead of |
---|
550 | `inline'. |
---|
551 | |
---|
552 | Other C compilers won't accept these alternative keywords; if you |
---|
553 | want to compile with another compiler, you can define the alternate |
---|
554 | keywords as macros to replace them with the customary keywords. It |
---|
555 | looks like this: |
---|
556 | |
---|
557 | #ifndef __GNUC__ |
---|
558 | #define __asm__ asm |
---|
559 | #endif |
---|
560 | |
---|
561 | `-pedantic' causes warnings for many GNU C extensions. You can |
---|
562 | prevent such warnings within one expression by writing `__extension__' |
---|
563 | before the expression. `__extension__' has no effect aside from this. |
---|
564 | |
---|
565 | |
---|
566 | File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions |
---|
567 | |
---|
568 | Incomplete `enum' Types |
---|
569 | ======================= |
---|
570 | |
---|
571 | You can define an `enum' tag without specifying its possible values. |
---|
572 | This results in an incomplete type, much like what you get if you write |
---|
573 | `struct foo' without describing the elements. A later declaration |
---|
574 | which does specify the possible values completes the type. |
---|
575 | |
---|
576 | You can't allocate variables or storage using the type while it is |
---|
577 | incomplete. However, you can work with pointers to that type. |
---|
578 | |
---|
579 | This extension may not be very useful, but it makes the handling of |
---|
580 | `enum' more consistent with the way `struct' and `union' are handled. |
---|
581 | |
---|
582 | This extension is not supported by GNU C++. |
---|
583 | |
---|
584 | |
---|
585 | File: gcc.info, Node: Function Names, Next: Return Address, Prev: Incomplete Enums, Up: C Extensions |
---|
586 | |
---|
587 | Function Names as Strings |
---|
588 | ========================= |
---|
589 | |
---|
590 | GNU CC predefines two string variables to be the name of the current |
---|
591 | function. The variable `__FUNCTION__' is the name of the function as |
---|
592 | it appears in the source. The variable `__PRETTY_FUNCTION__' is the |
---|
593 | name of the function pretty printed in a language specific fashion. |
---|
594 | |
---|
595 | These names are always the same in a C function, but in a C++ |
---|
596 | function they may be different. For example, this program: |
---|
597 | |
---|
598 | extern "C" { |
---|
599 | extern int printf (char *, ...); |
---|
600 | } |
---|
601 | |
---|
602 | class a { |
---|
603 | public: |
---|
604 | sub (int i) |
---|
605 | { |
---|
606 | printf ("__FUNCTION__ = %s\n", __FUNCTION__); |
---|
607 | printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); |
---|
608 | } |
---|
609 | }; |
---|
610 | |
---|
611 | int |
---|
612 | main (void) |
---|
613 | { |
---|
614 | a ax; |
---|
615 | ax.sub (0); |
---|
616 | return 0; |
---|
617 | } |
---|
618 | |
---|
619 | gives this output: |
---|
620 | |
---|
621 | __FUNCTION__ = sub |
---|
622 | __PRETTY_FUNCTION__ = int a::sub (int) |
---|
623 | |
---|
624 | These names are not macros: they are predefined string variables. |
---|
625 | For example, `#ifdef __FUNCTION__' does not have any special meaning |
---|
626 | inside a function, since the preprocessor does not do anything special |
---|
627 | with the identifier `__FUNCTION__'. |
---|
628 | |
---|
629 | |
---|
630 | File: gcc.info, Node: Return Address, Prev: Function Names, Up: C Extensions |
---|
631 | |
---|
632 | Getting the Return or Frame Address of a Function |
---|
633 | ================================================= |
---|
634 | |
---|
635 | These functions may be used to get information about the callers of a |
---|
636 | function. |
---|
637 | |
---|
638 | `__builtin_return_address (LEVEL)' |
---|
639 | This function returns the return address of the current function, |
---|
640 | or of one of its callers. The LEVEL argument is number of frames |
---|
641 | to scan up the call stack. A value of `0' yields the return |
---|
642 | address of the current function, a value of `1' yields the return |
---|
643 | address of the caller of the current function, and so forth. |
---|
644 | |
---|
645 | The LEVEL argument must be a constant integer. |
---|
646 | |
---|
647 | On some machines it may be impossible to determine the return |
---|
648 | address of any function other than the current one; in such cases, |
---|
649 | or when the top of the stack has been reached, this function will |
---|
650 | return `0'. |
---|
651 | |
---|
652 | This function should only be used with a non-zero argument for |
---|
653 | debugging purposes. |
---|
654 | |
---|
655 | `__builtin_frame_address (LEVEL)' |
---|
656 | This function is similar to `__builtin_return_address', but it |
---|
657 | returns the address of the function frame rather than the return |
---|
658 | address of the function. Calling `__builtin_frame_address' with a |
---|
659 | value of `0' yields the frame address of the current function, a |
---|
660 | value of `1' yields the frame address of the caller of the current |
---|
661 | function, and so forth. |
---|
662 | |
---|
663 | The frame is the area on the stack which holds local variables and |
---|
664 | saved registers. The frame address is normally the address of the |
---|
665 | first word pushed on to the stack by the function. However, the |
---|
666 | exact definition depends upon the processor and the calling |
---|
667 | convention. If the processor has a dedicated frame pointer |
---|
668 | register, and the function has a frame, then |
---|
669 | `__builtin_frame_address' will return the value of the frame |
---|
670 | pointer register. |
---|
671 | |
---|
672 | The caveats that apply to `__builtin_return_address' apply to this |
---|
673 | function as well. |
---|
674 | |
---|
675 | |
---|
676 | File: gcc.info, Node: C++ Extensions, Next: Gcov, Prev: C Extensions, Up: Top |
---|
677 | |
---|
678 | Extensions to the C++ Language |
---|
679 | ****************************** |
---|
680 | |
---|
681 | The GNU compiler provides these extensions to the C++ language (and |
---|
682 | you can also use most of the C language extensions in your C++ |
---|
683 | programs). If you want to write code that checks whether these |
---|
684 | features are available, you can test for the GNU compiler the same way |
---|
685 | as for C programs: check for a predefined macro `__GNUC__'. You can |
---|
686 | also use `__GNUG__' to test specifically for GNU C++ (*note Standard |
---|
687 | Predefined Macros: (cpp.info)Standard Predefined.). |
---|
688 | |
---|
689 | * Menu: |
---|
690 | |
---|
691 | * Naming Results:: Giving a name to C++ function return values. |
---|
692 | * Min and Max:: C++ Minimum and maximum operators. |
---|
693 | * Destructors and Goto:: Goto is safe to use in C++ even when destructors |
---|
694 | are needed. |
---|
695 | * C++ Interface:: You can use a single C++ header file for both |
---|
696 | declarations and definitions. |
---|
697 | * Template Instantiation:: Methods for ensuring that exactly one copy of |
---|
698 | each needed template instantiation is emitted. |
---|
699 | * C++ Signatures:: You can specify abstract types to get subtype |
---|
700 | polymorphism independent from inheritance. |
---|
701 | |
---|
702 | |
---|
703 | File: gcc.info, Node: Naming Results, Next: Min and Max, Up: C++ Extensions |
---|
704 | |
---|
705 | Named Return Values in C++ |
---|
706 | ========================== |
---|
707 | |
---|
708 | GNU C++ extends the function-definition syntax to allow you to |
---|
709 | specify a name for the result of a function outside the body of the |
---|
710 | definition, in C++ programs: |
---|
711 | |
---|
712 | TYPE |
---|
713 | FUNCTIONNAME (ARGS) return RESULTNAME; |
---|
714 | { |
---|
715 | ... |
---|
716 | BODY |
---|
717 | ... |
---|
718 | } |
---|
719 | |
---|
720 | You can use this feature to avoid an extra constructor call when a |
---|
721 | function result has a class type. For example, consider a function |
---|
722 | `m', declared as `X v = m ();', whose result is of class `X': |
---|
723 | |
---|
724 | X |
---|
725 | m () |
---|
726 | { |
---|
727 | X b; |
---|
728 | b.a = 23; |
---|
729 | return b; |
---|
730 | } |
---|
731 | |
---|
732 | Although `m' appears to have no arguments, in fact it has one |
---|
733 | implicit argument: the address of the return value. At invocation, the |
---|
734 | address of enough space to hold `v' is sent in as the implicit argument. |
---|
735 | Then `b' is constructed and its `a' field is set to the value 23. |
---|
736 | Finally, a copy constructor (a constructor of the form `X(X&)') is |
---|
737 | applied to `b', with the (implicit) return value location as the |
---|
738 | target, so that `v' is now bound to the return value. |
---|
739 | |
---|
740 | But this is wasteful. The local `b' is declared just to hold |
---|
741 | something that will be copied right out. While a compiler that |
---|
742 | combined an "elision" algorithm with interprocedural data flow analysis |
---|
743 | could conceivably eliminate all of this, it is much more practical to |
---|
744 | allow you to assist the compiler in generating efficient code by |
---|
745 | manipulating the return value explicitly, thus avoiding the local |
---|
746 | variable and copy constructor altogether. |
---|
747 | |
---|
748 | Using the extended GNU C++ function-definition syntax, you can avoid |
---|
749 | the temporary allocation and copying by naming `r' as your return value |
---|
750 | at the outset, and assigning to its `a' field directly: |
---|
751 | |
---|
752 | X |
---|
753 | m () return r; |
---|
754 | { |
---|
755 | r.a = 23; |
---|
756 | } |
---|
757 | |
---|
758 | The declaration of `r' is a standard, proper declaration, whose effects |
---|
759 | are executed *before* any of the body of `m'. |
---|
760 | |
---|
761 | Functions of this type impose no additional restrictions; in |
---|
762 | particular, you can execute `return' statements, or return implicitly by |
---|
763 | reaching the end of the function body ("falling off the edge"). Cases |
---|
764 | like |
---|
765 | |
---|
766 | X |
---|
767 | m () return r (23); |
---|
768 | { |
---|
769 | return; |
---|
770 | } |
---|
771 | |
---|
772 | (or even `X m () return r (23); { }') are unambiguous, since the return |
---|
773 | value `r' has been initialized in either case. The following code may |
---|
774 | be hard to read, but also works predictably: |
---|
775 | |
---|
776 | X |
---|
777 | m () return r; |
---|
778 | { |
---|
779 | X b; |
---|
780 | return b; |
---|
781 | } |
---|
782 | |
---|
783 | The return value slot denoted by `r' is initialized at the outset, |
---|
784 | but the statement `return b;' overrides this value. The compiler deals |
---|
785 | with this by destroying `r' (calling the destructor if there is one, or |
---|
786 | doing nothing if there is not), and then reinitializing `r' with `b'. |
---|
787 | |
---|
788 | This extension is provided primarily to help people who use |
---|
789 | overloaded operators, where there is a great need to control not just |
---|
790 | the arguments, but the return values of functions. For classes where |
---|
791 | the copy constructor incurs a heavy performance penalty (especially in |
---|
792 | the common case where there is a quick default constructor), this is a |
---|
793 | major savings. The disadvantage of this extension is that you do not |
---|
794 | control when the default constructor for the return value is called: it |
---|
795 | is always called at the beginning. |
---|
796 | |
---|
797 | |
---|
798 | File: gcc.info, Node: Min and Max, Next: Destructors and Goto, Prev: Naming Results, Up: C++ Extensions |
---|
799 | |
---|
800 | Minimum and Maximum Operators in C++ |
---|
801 | ==================================== |
---|
802 | |
---|
803 | It is very convenient to have operators which return the "minimum" |
---|
804 | or the "maximum" of two arguments. In GNU C++ (but not in GNU C), |
---|
805 | |
---|
806 | `A <? B' |
---|
807 | is the "minimum", returning the smaller of the numeric values A |
---|
808 | and B; |
---|
809 | |
---|
810 | `A >? B' |
---|
811 | is the "maximum", returning the larger of the numeric values A and |
---|
812 | B. |
---|
813 | |
---|
814 | These operations are not primitive in ordinary C++, since you can |
---|
815 | use a macro to return the minimum of two things in C++, as in the |
---|
816 | following example. |
---|
817 | |
---|
818 | #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) |
---|
819 | |
---|
820 | You might then use `int min = MIN (i, j);' to set MIN to the minimum |
---|
821 | value of variables I and J. |
---|
822 | |
---|
823 | However, side effects in `X' or `Y' may cause unintended behavior. |
---|
824 | For example, `MIN (i++, j++)' will fail, incrementing the smaller |
---|
825 | counter twice. A GNU C extension allows you to write safe macros that |
---|
826 | avoid this kind of problem (*note Naming an Expression's Type: Naming |
---|
827 | Types.). However, writing `MIN' and `MAX' as macros also forces you to |
---|
828 | use function-call notation for a fundamental arithmetic operation. |
---|
829 | Using GNU C++ extensions, you can write `int min = i <? j;' instead. |
---|
830 | |
---|
831 | Since `<?' and `>?' are built into the compiler, they properly |
---|
832 | handle expressions with side-effects; `int min = i++ <? j++;' works |
---|
833 | correctly. |
---|
834 | |
---|
835 | |
---|
836 | File: gcc.info, Node: Destructors and Goto, Next: C++ Interface, Prev: Min and Max, Up: C++ Extensions |
---|
837 | |
---|
838 | `goto' and Destructors in GNU C++ |
---|
839 | ================================= |
---|
840 | |
---|
841 | In C++ programs, you can safely use the `goto' statement. When you |
---|
842 | use it to exit a block which contains aggregates requiring destructors, |
---|
843 | the destructors will run before the `goto' transfers control. |
---|
844 | |
---|
845 | The compiler still forbids using `goto' to *enter* a scope that |
---|
846 | requires constructors. |
---|
847 | |
---|
848 | |
---|
849 | File: gcc.info, Node: C++ Interface, Next: Template Instantiation, Prev: Destructors and Goto, Up: C++ Extensions |
---|
850 | |
---|
851 | Declarations and Definitions in One Header |
---|
852 | ========================================== |
---|
853 | |
---|
854 | C++ object definitions can be quite complex. In principle, your |
---|
855 | source code will need two kinds of things for each object that you use |
---|
856 | across more than one source file. First, you need an "interface" |
---|
857 | specification, describing its structure with type declarations and |
---|
858 | function prototypes. Second, you need the "implementation" itself. It |
---|
859 | can be tedious to maintain a separate interface description in a header |
---|
860 | file, in parallel to the actual implementation. It is also dangerous, |
---|
861 | since separate interface and implementation definitions may not remain |
---|
862 | parallel. |
---|
863 | |
---|
864 | With GNU C++, you can use a single header file for both purposes. |
---|
865 | |
---|
866 | *Warning:* The mechanism to specify this is in transition. For the |
---|
867 | nonce, you must use one of two `#pragma' commands; in a future |
---|
868 | release of GNU C++, an alternative mechanism will make these |
---|
869 | `#pragma' commands unnecessary. |
---|
870 | |
---|
871 | The header file contains the full definitions, but is marked with |
---|
872 | `#pragma interface' in the source code. This allows the compiler to |
---|
873 | use the header file only as an interface specification when ordinary |
---|
874 | source files incorporate it with `#include'. In the single source file |
---|
875 | where the full implementation belongs, you can use either a naming |
---|
876 | convention or `#pragma implementation' to indicate this alternate use |
---|
877 | of the header file. |
---|
878 | |
---|
879 | `#pragma interface' |
---|
880 | `#pragma interface "SUBDIR/OBJECTS.h"' |
---|
881 | Use this directive in *header files* that define object classes, |
---|
882 | to save space in most of the object files that use those classes. |
---|
883 | Normally, local copies of certain information (backup copies of |
---|
884 | inline member functions, debugging information, and the internal |
---|
885 | tables that implement virtual functions) must be kept in each |
---|
886 | object file that includes class definitions. You can use this |
---|
887 | pragma to avoid such duplication. When a header file containing |
---|
888 | `#pragma interface' is included in a compilation, this auxiliary |
---|
889 | information will not be generated (unless the main input source |
---|
890 | file itself uses `#pragma implementation'). Instead, the object |
---|
891 | files will contain references to be resolved at link time. |
---|
892 | |
---|
893 | The second form of this directive is useful for the case where you |
---|
894 | have multiple headers with the same name in different directories. |
---|
895 | If you use this form, you must specify the same string to `#pragma |
---|
896 | implementation'. |
---|
897 | |
---|
898 | `#pragma implementation' |
---|
899 | `#pragma implementation "OBJECTS.h"' |
---|
900 | Use this pragma in a *main input file*, when you want full output |
---|
901 | from included header files to be generated (and made globally |
---|
902 | visible). The included header file, in turn, should use `#pragma |
---|
903 | interface'. Backup copies of inline member functions, debugging |
---|
904 | information, and the internal tables used to implement virtual |
---|
905 | functions are all generated in implementation files. |
---|
906 | |
---|
907 | If you use `#pragma implementation' with no argument, it applies to |
---|
908 | an include file with the same basename(1) as your source file. |
---|
909 | For example, in `allclass.cc', giving just `#pragma implementation' |
---|
910 | by itself is equivalent to `#pragma implementation "allclass.h"'. |
---|
911 | |
---|
912 | In versions of GNU C++ prior to 2.6.0 `allclass.h' was treated as |
---|
913 | an implementation file whenever you would include it from |
---|
914 | `allclass.cc' even if you never specified `#pragma |
---|
915 | implementation'. This was deemed to be more trouble than it was |
---|
916 | worth, however, and disabled. |
---|
917 | |
---|
918 | If you use an explicit `#pragma implementation', it must appear in |
---|
919 | your source file *before* you include the affected header files. |
---|
920 | |
---|
921 | Use the string argument if you want a single implementation file to |
---|
922 | include code from multiple header files. (You must also use |
---|
923 | `#include' to include the header file; `#pragma implementation' |
---|
924 | only specifies how to use the file--it doesn't actually include |
---|
925 | it.) |
---|
926 | |
---|
927 | There is no way to split up the contents of a single header file |
---|
928 | into multiple implementation files. |
---|
929 | |
---|
930 | `#pragma implementation' and `#pragma interface' also have an effect |
---|
931 | on function inlining. |
---|
932 | |
---|
933 | If you define a class in a header file marked with `#pragma |
---|
934 | interface', the effect on a function defined in that class is similar to |
---|
935 | an explicit `extern' declaration--the compiler emits no code at all to |
---|
936 | define an independent version of the function. Its definition is used |
---|
937 | only for inlining with its callers. |
---|
938 | |
---|
939 | Conversely, when you include the same header file in a main source |
---|
940 | file that declares it as `#pragma implementation', the compiler emits |
---|
941 | code for the function itself; this defines a version of the function |
---|
942 | that can be found via pointers (or by callers compiled without |
---|
943 | inlining). If all calls to the function can be inlined, you can avoid |
---|
944 | emitting the function by compiling with `-fno-implement-inlines'. If |
---|
945 | any calls were not inlined, you will get linker errors. |
---|
946 | |
---|
947 | ---------- Footnotes ---------- |
---|
948 | |
---|
949 | (1) A file's "basename" was the name stripped of all leading path |
---|
950 | information and of trailing suffixes, such as `.h' or `.C' or `.cc'. |
---|
951 | |
---|
952 | |
---|
953 | File: gcc.info, Node: Template Instantiation, Next: C++ Signatures, Prev: C++ Interface, Up: C++ Extensions |
---|
954 | |
---|
955 | Where's the Template? |
---|
956 | ===================== |
---|
957 | |
---|
958 | C++ templates are the first language feature to require more |
---|
959 | intelligence from the environment than one usually finds on a UNIX |
---|
960 | system. Somehow the compiler and linker have to make sure that each |
---|
961 | template instance occurs exactly once in the executable if it is needed, |
---|
962 | and not at all otherwise. There are two basic approaches to this |
---|
963 | problem, which I will refer to as the Borland model and the Cfront |
---|
964 | model. |
---|
965 | |
---|
966 | Borland model |
---|
967 | Borland C++ solved the template instantiation problem by adding |
---|
968 | the code equivalent of common blocks to their linker; the compiler |
---|
969 | emits template instances in each translation unit that uses them, |
---|
970 | and the linker collapses them together. The advantage of this |
---|
971 | model is that the linker only has to consider the object files |
---|
972 | themselves; there is no external complexity to worry about. This |
---|
973 | disadvantage is that compilation time is increased because the |
---|
974 | template code is being compiled repeatedly. Code written for this |
---|
975 | model tends to include definitions of all templates in the header |
---|
976 | file, since they must be seen to be instantiated. |
---|
977 | |
---|
978 | Cfront model |
---|
979 | The AT&T C++ translator, Cfront, solved the template instantiation |
---|
980 | problem by creating the notion of a template repository, an |
---|
981 | automatically maintained place where template instances are |
---|
982 | stored. A more modern version of the repository works as follows: |
---|
983 | As individual object files are built, the compiler places any |
---|
984 | template definitions and instantiations encountered in the |
---|
985 | repository. At link time, the link wrapper adds in the objects in |
---|
986 | the repository and compiles any needed instances that were not |
---|
987 | previously emitted. The advantages of this model are more optimal |
---|
988 | compilation speed and the ability to use the system linker; to |
---|
989 | implement the Borland model a compiler vendor also needs to |
---|
990 | replace the linker. The disadvantages are vastly increased |
---|
991 | complexity, and thus potential for error; for some code this can be |
---|
992 | just as transparent, but in practice it can been very difficult to |
---|
993 | build multiple programs in one directory and one program in |
---|
994 | multiple directories. Code written for this model tends to |
---|
995 | separate definitions of non-inline member templates into a |
---|
996 | separate file, which should be compiled separately. |
---|
997 | |
---|
998 | When used with GNU ld version 2.8 or later on an ELF system such as |
---|
999 | Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the |
---|
1000 | Borland model. On other systems, g++ implements neither automatic |
---|
1001 | model. |
---|
1002 | |
---|
1003 | A future version of g++ will support a hybrid model whereby the |
---|
1004 | compiler will emit any instantiations for which the template definition |
---|
1005 | is included in the compile, and store template definitions and |
---|
1006 | instantiation context information into the object file for the rest. |
---|
1007 | The link wrapper will extract that information as necessary and invoke |
---|
1008 | the compiler to produce the remaining instantiations. The linker will |
---|
1009 | then combine duplicate instantiations. |
---|
1010 | |
---|
1011 | In the mean time, you have the following options for dealing with |
---|
1012 | template instantiations: |
---|
1013 | |
---|
1014 | 1. Compile your code with `-fno-implicit-templates' to disable the |
---|
1015 | implicit generation of template instances, and explicitly |
---|
1016 | instantiate all the ones you use. This approach requires more |
---|
1017 | knowledge of exactly which instances you need than do the others, |
---|
1018 | but it's less mysterious and allows greater control. You can |
---|
1019 | scatter the explicit instantiations throughout your program, |
---|
1020 | perhaps putting them in the translation units where the instances |
---|
1021 | are used or the translation units that define the templates |
---|
1022 | themselves; you can put all of the explicit instantiations you |
---|
1023 | need into one big file; or you can create small files like |
---|
1024 | |
---|
1025 | #include "Foo.h" |
---|
1026 | #include "Foo.cc" |
---|
1027 | |
---|
1028 | template class Foo<int>; |
---|
1029 | template ostream& operator << |
---|
1030 | (ostream&, const Foo<int>&); |
---|
1031 | |
---|
1032 | for each of the instances you need, and create a template |
---|
1033 | instantiation library from those. |
---|
1034 | |
---|
1035 | If you are using Cfront-model code, you can probably get away with |
---|
1036 | not using `-fno-implicit-templates' when compiling files that don't |
---|
1037 | `#include' the member template definitions. |
---|
1038 | |
---|
1039 | If you use one big file to do the instantiations, you may want to |
---|
1040 | compile it without `-fno-implicit-templates' so you get all of the |
---|
1041 | instances required by your explicit instantiations (but not by any |
---|
1042 | other files) without having to specify them as well. |
---|
1043 | |
---|
1044 | g++ has extended the template instantiation syntax outlined in the |
---|
1045 | Working Paper to allow forward declaration of explicit |
---|
1046 | instantiations, explicit instantiation of members of template |
---|
1047 | classes and instantiation of the compiler support data for a |
---|
1048 | template class (i.e. the vtable) without instantiating any of its |
---|
1049 | members: |
---|
1050 | |
---|
1051 | extern template int max (int, int); |
---|
1052 | template void Foo<int>::f (); |
---|
1053 | inline template class Foo<int>; |
---|
1054 | |
---|
1055 | 2. Do nothing. Pretend g++ does implement automatic instantiation |
---|
1056 | management. Code written for the Borland model will work fine, but |
---|
1057 | each translation unit will contain instances of each of the |
---|
1058 | templates it uses. In a large program, this can lead to an |
---|
1059 | unacceptable amount of code duplication. |
---|
1060 | |
---|
1061 | 3. Add `#pragma interface' to all files containing template |
---|
1062 | definitions. For each of these files, add `#pragma implementation |
---|
1063 | "FILENAME"' to the top of some `.C' file which `#include's it. |
---|
1064 | Then compile everything with `-fexternal-templates'. The |
---|
1065 | templates will then only be expanded in the translation unit which |
---|
1066 | implements them (i.e. has a `#pragma implementation' line for the |
---|
1067 | file where they live); all other files will use external |
---|
1068 | references. If you're lucky, everything should work properly. If |
---|
1069 | you get undefined symbol errors, you need to make sure that each |
---|
1070 | template instance which is used in the program is used in the file |
---|
1071 | which implements that template. If you don't have any use for a |
---|
1072 | particular instance in that file, you can just instantiate it |
---|
1073 | explicitly, using the syntax from the latest C++ working paper: |
---|
1074 | |
---|
1075 | template class A<int>; |
---|
1076 | template ostream& operator << (ostream&, const A<int>&); |
---|
1077 | |
---|
1078 | This strategy will work with code written for either model. If |
---|
1079 | you are using code written for the Cfront model, the file |
---|
1080 | containing a class template and the file containing its member |
---|
1081 | templates should be implemented in the same translation unit. |
---|
1082 | |
---|
1083 | A slight variation on this approach is to instead use the flag |
---|
1084 | `-falt-external-templates'; this flag causes template instances to |
---|
1085 | be emitted in the translation unit that implements the header |
---|
1086 | where they are first instantiated, rather than the one which |
---|
1087 | implements the file where the templates are defined. This header |
---|
1088 | must be the same in all translation units, or things are likely to |
---|
1089 | break. |
---|
1090 | |
---|
1091 | *Note Declarations and Definitions in One Header: C++ Interface, |
---|
1092 | for more discussion of these pragmas. |
---|
1093 | |
---|