OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-dev/] [or1k-gcc/] [gcc/] [fortran/] [gfc-internals.texi] - Blame information for rev 713

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 712 jeremybenn
\input texinfo  @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename gfc-internals.info
4
@set copyrights-gfortran 2007, 2008, 2009, 2010
5
 
6
@include gcc-common.texi
7
 
8
@synindex tp cp
9
 
10
@settitle GNU Fortran Compiler Internals
11
 
12
@c %**end of header
13
 
14
@c Use with @@smallbook.
15
 
16
@c %** start of document
17
 
18
@c Cause even numbered pages to be printed on the left hand side of
19
@c the page and odd numbered pages to be printed on the right hand
20
@c side of the page.  Using this, you can print on both sides of a
21
@c sheet of paper and have the text on the same part of the sheet.
22
 
23
@c The text on right hand pages is pushed towards the right hand
24
@c margin and the text on left hand pages is pushed toward the left
25
@c hand margin.
26
@c (To provide the reverse effect, set bindingoffset to -0.75in.)
27
 
28
@c @tex
29
@c \global\bindingoffset=0.75in
30
@c \global\normaloffset =0.75in
31
@c @end tex
32
 
33
@copying
34
Copyright @copyright{} @value{copyrights-gfortran} Free Software Foundation,
35
Inc.
36
 
37
Permission is granted to copy, distribute and/or modify this document
38
under the terms of the GNU Free Documentation License, Version 1.3 or
39
any later version published by the Free Software Foundation; with the
40
Invariant Sections being ``Funding Free Software'', the Front-Cover
41
Texts being (a) (see below), and with the Back-Cover Texts being (b)
42
(see below).  A copy of the license is included in the section entitled
43
``GNU Free Documentation License''.
44
 
45
(a) The FSF's Front-Cover Text is:
46
 
47
     A GNU Manual
48
 
49
(b) The FSF's Back-Cover Text is:
50
 
51
     You have freedom to copy and modify this GNU Manual, like GNU
52
     software.  Copies published by the Free Software Foundation raise
53
     funds for GNU development.
54
@end copying
55
 
56
@ifinfo
57
@dircategory Software development
58
@direntry
59
* gfortran: (gfortran).                  The GNU Fortran Compiler.
60
@end direntry
61
This file documents the internals of the GNU Fortran
62
compiler, (@command{gfortran}).
63
 
64
Published by the Free Software Foundation
65
51 Franklin Street, Fifth Floor
66
Boston, MA 02110-1301 USA
67
 
68
@insertcopying
69
@end ifinfo
70
 
71
 
72
@setchapternewpage odd
73
@titlepage
74
@title GNU Fortran Internals
75
@versionsubtitle
76
@author The @t{gfortran} team
77
@page
78
@vskip 0pt plus 1filll
79
Published by the Free Software Foundation@*
80
51 Franklin Street, Fifth Floor@*
81
Boston, MA 02110-1301, USA@*
82
@c Last printed ??ber, 19??.@*
83
@c Printed copies are available for $? each.@*
84
@c ISBN ???
85
@sp 1
86
@insertcopying
87
@end titlepage
88
 
89
@summarycontents
90
@contents
91
 
92
@page
93
 
94
@c ---------------------------------------------------------------------
95
@c TexInfo table of contents.
96
@c ---------------------------------------------------------------------
97
 
98
@ifnottex
99
@node Top
100
@top Introduction
101
@cindex Introduction
102
 
103
This manual documents the internals of @command{gfortran},
104
the GNU Fortran compiler.
105
 
106
@ifset DEVELOPMENT
107
@emph{Warning:} This document, and the compiler it describes, are still
108
under development.  While efforts are made to keep it up-to-date, it might
109
not accurately reflect the status of the most recent GNU Fortran compiler.
110
@end ifset
111
 
112
@comment
113
@comment  When you add a new menu item, please keep the right hand
114
@comment  aligned to the same column.  Do not use tabs.  This provides
115
@comment  better formatting.
116
@comment
117
@menu
118
* Introduction::           About this manual.
119
* User Interface::         Code that Interacts with the User.
120
* Frontend Data Structures::
121
                           Data structures used by the frontend
122
* Object Orientation::     Internals of Fortran 2003 OOP features.
123
* LibGFortran::            The LibGFortran Runtime Library.
124
* GNU Free Documentation License::
125
                           How you can copy and share this manual.
126
* Index::                  Index of this documentation.
127
@end menu
128
@end ifnottex
129
 
130
@c ---------------------------------------------------------------------
131
@c Introduction
132
@c ---------------------------------------------------------------------
133
 
134
@node Introduction
135
@chapter Introduction
136
 
137
@c The following duplicates the text on the TexInfo table of contents.
138
@iftex
139
This manual documents the internals of @command{gfortran}, the GNU Fortran
140
compiler.
141
 
142
@ifset DEVELOPMENT
143
@emph{Warning:} This document, and the compiler it describes, are still
144
under development.  While efforts are made to keep it up-to-date, it
145
might not accurately reflect the status of the most recent GNU Fortran
146
compiler.
147
@end ifset
148
@end iftex
149
 
150
At present, this manual is very much a work in progress, containing
151
miscellaneous notes about the internals of the compiler.  It is hoped
152
that at some point in the future it will become a reasonably complete
153
guide; in the interim, GNU Fortran developers are strongly encouraged to
154
contribute to it as a way of keeping notes while working on the
155
compiler.
156
 
157
 
158
@c ---------------------------------------------------------------------
159
@c Code that Interacts with the User
160
@c ---------------------------------------------------------------------
161
 
162
@node User Interface
163
@chapter Code that Interacts with the User
164
 
165
@menu
166
* Command-Line Options::    Command-Line Options.
167
* Error Handling::          Error Handling.
168
@end menu
169
 
170
 
171
@c ---------------------------------------------------------------------
172
@c Command-Line Options
173
@c ---------------------------------------------------------------------
174
 
175
@node Command-Line Options
176
@section Command-Line Options
177
 
178
Command-line options for @command{gfortran} involve four interrelated
179
pieces within the Fortran compiler code.
180
 
181
The relevant command-line flag is defined in @file{lang.opt}, according
182
to the documentation in @ref{Options,, Options, gccint, GNU Compiler
183
Collection Internals}.  This is then processed by the overall GCC
184
machinery to create the code that enables @command{gfortran} and
185
@command{gcc} to recognize the option in the command-line arguments and
186
call the relevant handler function.
187
 
188
This generated code calls the @code{gfc_handle_option} code in
189
@file{options.c} with an enumerator variable indicating which option is
190
to be processed, and the relevant integer or string values associated
191
with that option flag.  Typically, @code{gfc_handle_option} uses these
192
arguments to set global flags which record the option states.
193
 
194
The global flags that record the option states are stored in the
195
@code{gfc_option_t} struct, which is defined in @file{gfortran.h}.
196
Before the options are processed, initial values for these flags are set
197
in @code{gfc_init_option} in @file{options.c}; these become the default
198
values for the options.
199
 
200
 
201
 
202
@c ---------------------------------------------------------------------
203
@c Error Handling
204
@c ---------------------------------------------------------------------
205
 
206
@node Error Handling
207
@section Error Handling
208
 
209
The GNU Fortran compiler's parser operates by testing each piece of
210
source code against a variety of matchers.  In some cases, if these
211
matchers do not match the source code, they will store an error message
212
in a buffer.  If the parser later finds a matcher that does correctly
213
match the source code, then the buffered error is discarded.  However,
214
if the parser cannot find a match, then the buffered error message is
215
reported to the user.  This enables the compiler to provide more
216
meaningful error messages even in the many cases where (erroneous)
217
Fortran syntax is ambiguous due to things like the absence of reserved
218
keywords.
219
 
220
As an example of how this works, consider the following line:
221
@smallexample
222
IF = 3
223
@end smallexample
224
Hypothetically, this may get passed to the matcher for an @code{IF}
225
statement.  Since this could plausibly be an erroneous @code{IF}
226
statement, the matcher will buffer an error message reporting the
227
absence of an expected @samp{(} following an @code{IF}.  Since no
228
matchers reported an error-free match, however, the parser will also try
229
matching this against a variable assignment.  When @code{IF} is a valid
230
variable, this will be parsed as an assignment statement, and the error
231
discarded.  However, when @code{IF} is not a valid variable, this
232
buffered error message will be reported to the user.
233
 
234
The error handling code is implemented in @file{error.c}.  Errors are
235
normally entered into the buffer with the @code{gfc_error} function.
236
Warnings go through a similar buffering process, and are entered into
237
the buffer with @code{gfc_warning}.  There is also a special-purpose
238
function, @code{gfc_notify_std}, for things which have an error/warning
239
status that depends on the currently-selected language standard.
240
 
241
The @code{gfc_error_check} function checks the buffer for errors,
242
reports the error message to the user if one exists, clears the buffer,
243
and returns a flag to the user indicating whether or not an error
244
existed.  To check the state of the buffer without changing its state or
245
reporting the errors, the @code{gfc_error_flag_test} function can be
246
used.  The @code{gfc_clear_error} function will clear out any errors in
247
the buffer, without reporting them.  The @code{gfc_warning_check} and
248
@code{gfc_clear_warning} functions provide equivalent functionality for
249
the warning buffer.
250
 
251
Only one error and one warning can be in the buffers at a time, and
252
buffering another will overwrite the existing one.  In cases where one
253
may wish to work on a smaller piece of source code without disturbing an
254
existing error state, the @code{gfc_push_error}, @code{gfc_pop_error},
255
and @code{gfc_free_error} mechanism exists to implement a stack for the
256
error buffer.
257
 
258
For cases where an error or warning should be reported immediately
259
rather than buffered, the @code{gfc_error_now} and
260
@code{gfc_warning_now} functions can be used.  Normally, the compiler
261
will continue attempting to parse the program after an error has
262
occurred, but if this is not appropriate, the @code{gfc_fatal_error}
263
function should be used instead.  For errors that are always the result
264
of a bug somewhere in the compiler, the @code{gfc_internal_error}
265
function should be used.
266
 
267
The syntax for the strings used to produce the error/warning message in
268
the various error and warning functions is similar to the @code{printf}
269
syntax, with @samp{%}-escapes to insert variable values.  The details,
270
and the allowable codes, are documented in the @code{error_print}
271
function in @file{error.c}.
272
 
273
@c ---------------------------------------------------------------------
274
@c Frontend Data Structures
275
@c ---------------------------------------------------------------------
276
 
277
@node Frontend Data Structures
278
@chapter Frontend Data Structures
279
@cindex data structures
280
 
281
This chapter should describe the details necessary to understand how
282
the various @code{gfc_*} data are used and interact.  In general it is
283
advisable to read the code in @file{dump-parse-tree.c} as its routines
284
should exhaust all possible valid combinations of content for these
285
structures.
286
 
287
@menu
288
* gfc_code:: Representation of Executable Statements.
289
* gfc_expr:: Representation of Values and Expressions.
290
@end menu
291
 
292
 
293
@c gfc_code
294
@c --------
295
 
296
@node gfc_code
297
@section @code{gfc_code}
298
@cindex statement chaining
299
@tindex @code{gfc_code}
300
@tindex @code{struct gfc_code}
301
 
302
The executable statements in a program unit are represented by a
303
nested chain of @code{gfc_code} structures.  The type of statement is
304
identified by the @code{op} member of the structure, the different
305
possible values are enumerated in @code{gfc_exec_op}.  A special
306
member of this @code{enum} is @code{EXEC_NOP} which is used to
307
represent the various @code{END} statements if they carry a label.
308
Depending on the type of statement some of the other fields will be
309
filled in.  Fields that are generally applicable are the @code{next}
310
and @code{here} fields.  The former points to the next statement in
311
the current block or is @code{NULL} if the current statement is the
312
last in a block, @code{here} points to the statement label of the
313
current statement.
314
 
315
If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
316
it starts a block, i.e.@: a nested level in the program.  In order to
317
represent this, the @code{block} member is set to point to a
318
@code{gfc_code} structure whose @code{next} member starts the chain of
319
statements inside the block; this structure's @code{op} member should be set to
320
the same value as the parent structure's @code{op} member.  The @code{SELECT}
321
and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
322
and @code{ELSE} blocks or the various @code{CASE}s, respectively).  These chains
323
are linked-lists formed by the @code{block} members.
324
 
325
Consider the following example code:
326
 
327
@example
328
IF (foo < 20) THEN
329
  PRINT *, "Too small"
330
  foo = 20
331
ELSEIF (foo > 50) THEN
332
  PRINT *, "Too large"
333
  foo = 50
334
ELSE
335
  PRINT *, "Good"
336
END IF
337
@end example
338
 
339
This statement-block will be represented in the internal gfortran tree as
340
follows, were the horizontal link-chains are those induced by the @code{next}
341
members and vertical links down are those of @code{block}. @samp{==|} and
342
@samp{--|} mean @code{NULL} pointers to mark the end of a chain:
343
 
344
@example
345
... ==> IF ==> ...
346
        |
347
        +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
348
             |
349
             +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
350
                  |
351
                  +--> ELSE ==> PRINT *, "Good" ==|
352
                       |
353
                       +--|
354
@end example
355
 
356
 
357
@subsection IF Blocks
358
 
359
Conditionals are represented by @code{gfc_code} structures with their
360
@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
361
member must point to another @code{gfc_code} node that is the header of the
362
if-block.  This header's @code{op} member must be set to @code{EXEC_IF}, too,
363
its @code{expr} member holds the condition to check for, and its @code{next}
364
should point to the code-chain of the statements to execute if the condition is
365
true.
366
 
367
If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
368
@code{block} member of the if-block-header node points to yet another
369
@code{gfc_code} structure that is the header of the elseif- or else-block.  Its
370
structure is identical to that of the if-block-header, except that in case of an
371
@code{ELSE} block without a new condition the @code{expr} member should be
372
@code{NULL}.  This block can itself have its @code{block} member point to the
373
next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
374
 
375
 
376
@subsection Loops
377
 
378
@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
379
@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
380
to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
381
Their @code{block} member should point to a @code{gfc_code} structure heading
382
the code-chain of the loop body; its @code{op} member should be set to
383
@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.
384
 
385
For @code{DO WHILE} loops, the loop condition is stored on the top
386
@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
387
simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
388
the internal representation.
389
 
390
Similarly, @code{DO} loops with an iterator have instead of the condition their
391
@code{ext.iterator} member set to the correct values for the loop iterator
392
variable and its range.
393
 
394
 
395
@subsection @code{SELECT} Statements
396
 
397
A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
398
@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
399
to evaluate and test.  Its @code{block} member starts a list of @code{gfc_code}
400
structures linked together by their @code{block} members that stores the various
401
@code{CASE} parts.
402
 
403
Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
404
its @code{next} member points to the code-chain to be executed in the current
405
case-block, and @code{extx.case_list} contains the case-values this block
406
corresponds to.  The @code{block} member links to the next case in the list.
407
 
408
 
409
@subsection @code{BLOCK} and @code{ASSOCIATE}
410
 
411
The code related to a @code{BLOCK} statement is stored inside an
412
@code{gfc_code} structure (say @var{c})
413
with @code{c.op} set to @code{EXEC_BLOCK}.  The
414
@code{gfc_namespace} holding the locally defined variables of the
415
@code{BLOCK} is stored in @code{c.ext.block.ns}.  The code inside the
416
construct is in @code{c.code}.
417
 
418
@code{ASSOCIATE} constructs are based on @code{BLOCK} and thus also have
419
the internal storage structure described above (including @code{EXEC_BLOCK}).
420
However, for them @code{c.ext.block.assoc} is set additionally and points
421
to a linked list of @code{gfc_association_list} structures.  Those
422
structures basically store a link of associate-names to target expressions.
423
The associate-names themselves are still also added to the @code{BLOCK}'s
424
namespace as ordinary symbols, but they have their @code{gfc_symbol}'s
425
member @code{assoc} set also pointing to the association-list structure.
426
This way associate-names can be distinguished from ordinary variables
427
and their target expressions identified.
428
 
429
For association to expressions (as opposed to variables), at the very beginning
430
of the @code{BLOCK} construct assignments are automatically generated to
431
set the corresponding variables to their target expressions' values, and
432
later on the compiler simply disallows using such associate-names in contexts
433
that may change the value.
434
 
435
 
436
@c gfc_expr
437
@c --------
438
 
439
@node gfc_expr
440
@section @code{gfc_expr}
441
@tindex @code{gfc_expr}
442
@tindex @code{struct gfc_expr}
443
 
444
Expressions and ``values'', including constants, variable-, array- and
445
component-references as well as complex expressions consisting of operators and
446
function calls are internally represented as one or a whole tree of
447
@code{gfc_expr} objects.  The member @code{expr_type} specifies the overall
448
type of an expression (for instance, @code{EXPR_CONSTANT} for constants or
449
@code{EXPR_VARIABLE} for variable references).  The members @code{ts} and
450
@code{rank} as well as @code{shape}, which can be @code{NULL}, specify
451
the type, rank and, if applicable, shape of the whole expression or expression
452
tree of which the current structure is the root.  @code{where} is the locus of
453
this expression in the source code.
454
 
455
Depending on the flavor of the expression being described by the object
456
(that is, the value of its @code{expr_type} member), the corresponding structure
457
in the @code{value} union will usually contain additional data describing the
458
expression's value in a type-specific manner.  The @code{ref} member is used to
459
build chains of (array-, component- and substring-) references if the expression
460
in question contains such references, see below for details.
461
 
462
 
463
@subsection Constants
464
 
465
Scalar constants are represented by @code{gfc_expr} nodes with their
466
@code{expr_type} set to @code{EXPR_CONSTANT}.  The constant's value shall
467
already be known at compile-time and is stored in the @code{logical},
468
@code{integer}, @code{real}, @code{complex} or @code{character} struct inside
469
@code{value}, depending on the constant's type specification.
470
 
471
 
472
@subsection Operators
473
 
474
Operator-expressions are expressions that are the result of the execution of
475
some operator on one or two operands.  The expressions have an @code{expr_type}
476
of @code{EXPR_OP}.  Their @code{value.op} structure contains additional data.
477
 
478
@code{op1} and optionally @code{op2} if the operator is binary point to the
479
two operands, and @code{operator} or @code{uop} describe the operator that
480
should be evaluated on these operands, where @code{uop} describes a user-defined
481
operator.
482
 
483
 
484
@subsection Function Calls
485
 
486
If the expression is the return value of a function-call, its @code{expr_type}
487
is set to @code{EXPR_FUNCTION}, and @code{symtree} must point to the symtree
488
identifying the function to be called.  @code{value.function.actual} holds the
489
actual arguments given to the function as a linked list of
490
@code{gfc_actual_arglist} nodes.
491
 
492
The other members of @code{value.function} describe the function being called
493
in more detail, containing a link to the intrinsic symbol or user-defined
494
function symbol if the call is to an intrinsic or external function,
495
respectively.  These values are determined during resolution-phase from the
496
structure's @code{symtree} member.
497
 
498
A special case of function calls are ``component calls'' to type-bound
499
procedures; those have the @code{expr_type} @code{EXPR_COMPCALL} with
500
@code{value.compcall} containing the argument list and the procedure called,
501
while @code{symtree} and @code{ref} describe the object on which the procedure
502
was called in the same way as a @code{EXPR_VARIABLE} expression would.
503
@xref{Type-bound Procedures}.
504
 
505
 
506
@subsection Array- and Structure-Constructors
507
 
508
Array- and structure-constructors (one could probably call them ``array-'' and
509
``derived-type constants'') are @code{gfc_expr} structures with their
510
@code{expr_type} member set to @code{EXPR_ARRAY} or @code{EXPR_STRUCTURE},
511
respectively.  For structure constructors, @code{symtree} points to the
512
derived-type symbol for the type being constructed.
513
 
514
The values for initializing each array element or structure component are
515
stored as linked-list of @code{gfc_constructor} nodes in the
516
@code{value.constructor} member.
517
 
518
 
519
@subsection Null
520
 
521
@code{NULL} is a special value for pointers; it can be of different base types.
522
Such a @code{NULL} value is represented in the internal tree by a
523
@code{gfc_expr} node with @code{expr_type} @code{EXPR_NULL}.  If the base type
524
of the @code{NULL} expression is known, it is stored in @code{ts} (that's for
525
instance the case for default-initializers of @code{ALLOCATABLE} components),
526
but this member can also be set to @code{BT_UNKNOWN} if the information is not
527
available (for instance, when the expression is a pointer-initializer
528
@code{NULL()}).
529
 
530
 
531
@subsection Variables and Reference Expressions
532
 
533
Variable references are @code{gfc_expr} structures with their @code{expr_type}
534
set to @code{EXPR_VARIABLE}; their @code{symtree} should point to the variable
535
that is referenced.
536
 
537
For this type of expression, it's also possible to chain array-, component-
538
or substring-references to the original expression to get something like
539
@samp{struct%component(2:5)}, where @code{component} is either an array or
540
a @code{CHARACTER} member of @code{struct} that is of some derived-type.  Such a
541
chain of references is achieved by a linked list headed by @code{ref} of the
542
@code{gfc_expr} node.  For the example above it would be (@samp{==|} is the
543
last @code{NULL} pointer):
544
 
545
@smallexample
546
EXPR_VARIABLE(struct) ==> REF_COMPONENT(component) ==> REF_ARRAY(2:5) ==|
547
@end smallexample
548
 
549
If @code{component} is a string rather than an array, the last element would be
550
a @code{REF_SUBSTRING} reference, of course.  If the variable itself or some
551
component referenced is an array and the expression should reference the whole
552
array rather than being followed by an array-element or -section reference, a
553
@code{REF_ARRAY} reference must be built as the last element in the chain with
554
an array-reference type of @code{AR_FULL}. Consider this example code:
555
 
556
@smallexample
557
TYPE :: mytype
558
  INTEGER :: array(42)
559
END TYPE mytype
560
 
561
TYPE(mytype) :: variable
562
INTEGER :: local_array(5)
563
 
564
CALL do_something (variable%array, local_array)
565
@end smallexample
566
 
567
The @code{gfc_expr} nodes representing the arguments to the @samp{do_something}
568
call will have a reference-chain like this:
569
 
570
@smallexample
571
EXPR_VARIABLE(variable) ==> REF_COMPONENT(array) ==> REF_ARRAY(FULL) ==|
572
EXPR_VARIABLE(local_array) ==> REF_ARRAY(FULL) ==|
573
@end smallexample
574
 
575
 
576
@subsection Constant Substring References
577
 
578
@code{EXPR_SUBSTRING} is a special type of expression that encodes a substring
579
reference of a constant string, as in the following code snippet:
580
 
581
@smallexample
582
x = "abcde"(1:2)
583
@end smallexample
584
 
585
In this case, @code{value.character} contains the full string's data as if it
586
was a string constant, but the @code{ref} member is also set and points to a
587
substring reference as described in the subsection above.
588
 
589
 
590
@c ---------------------------------------------------------------------
591
@c F2003 OOP
592
@c ---------------------------------------------------------------------
593
 
594
@node Object Orientation
595
@chapter Internals of Fortran 2003 OOP Features
596
 
597
@menu
598
* Type-bound Procedures:: Type-bound procedures.
599
* Type-bound Operators::  Type-bound operators.
600
@end menu
601
 
602
 
603
@c Type-bound procedures
604
@c ---------------------
605
 
606
@node Type-bound Procedures
607
@section Type-bound Procedures
608
 
609
Type-bound procedures are stored in the @code{tb_sym_root} of the namespace
610
@code{f2k_derived} associated with the derived-type symbol as @code{gfc_symtree}
611
nodes.  The name and symbol of these symtrees corresponds to the binding-name
612
of the procedure, i.e. the name that is used to call it from the context of an
613
object of the derived-type.
614
 
615
In addition, this type of symtrees stores in @code{n.tb} a struct of type
616
@code{gfc_typebound_proc} containing the additional data needed:  The
617
binding attributes (like @code{PASS} and @code{NOPASS}, @code{NON_OVERRIDABLE}
618
or the access-specifier), the binding's target(s) and, if the current binding
619
overrides or extends an inherited binding of the same name, @code{overridden}
620
points to this binding's @code{gfc_typebound_proc} structure.
621
 
622
 
623
@subsection Specific Bindings
624
@c --------------------------
625
 
626
For specific bindings (declared with @code{PROCEDURE}), if they have a
627
passed-object argument, the passed-object dummy argument is first saved by its
628
name, and later during resolution phase the corresponding argument is looked for
629
and its position remembered as @code{pass_arg_num} in @code{gfc_typebound_proc}.
630
The binding's target procedure is pointed-to by @code{u.specific}.
631
 
632
@code{DEFERRED} bindings are just like ordinary specific bindings, except
633
that their @code{deferred} flag is set of course and that @code{u.specific}
634
points to their ``interface'' defining symbol (might be an abstract interface)
635
instead of the target procedure.
636
 
637
At the moment, all type-bound procedure calls are statically dispatched and
638
transformed into ordinary procedure calls at resolution time; their actual
639
argument list is updated to include at the right position the passed-object
640
argument, if applicable, and then a simple procedure call to the binding's
641
target procedure is built.  To handle dynamic dispatch in the future, this will
642
be extended to allow special code generation during the trans-phase to dispatch
643
based on the object's dynamic type.
644
 
645
 
646
@subsection Generic Bindings
647
@c -------------------------
648
 
649
Bindings declared as @code{GENERIC} store the specific bindings they target as
650
a linked list using nodes of type @code{gfc_tbp_generic} in @code{u.generic}.
651
For each specific target, the parser records its symtree and during resolution
652
this symtree is bound to the corresponding @code{gfc_typebound_proc} structure
653
of the specific target.
654
 
655
Calls to generic bindings are handled entirely in the resolution-phase, where
656
for the actual argument list present the matching specific binding is found
657
and the call's target procedure (@code{value.compcall.tbp}) is re-pointed to
658
the found specific binding and this call is subsequently handled by the logic
659
for specific binding calls.
660
 
661
 
662
@subsection Calls to Type-bound Procedures
663
@c ---------------------------------------
664
 
665
Calls to type-bound procedures are stored in the parse-tree as @code{gfc_expr}
666
nodes of type @code{EXPR_COMPCALL}.  Their @code{value.compcall.actual} saves
667
the actual argument list of the call and @code{value.compcall.tbp} points to the
668
@code{gfc_typebound_proc} structure of the binding to be called.  The object
669
in whose context the procedure was called is saved by combination of
670
@code{symtree} and @code{ref}, as if the expression was of type
671
@code{EXPR_VARIABLE}.
672
 
673
For code like this:
674
@smallexample
675
CALL myobj%procedure (arg1, arg2)
676
@end smallexample
677
@noindent
678
the @code{CALL} is represented in the parse-tree as a @code{gfc_code} node of
679
type @code{EXEC_COMPCALL}.  The @code{expr} member of this node holds an
680
expression of type @code{EXPR_COMPCALL} of the same structure as mentioned above
681
except that its target procedure is of course a @code{SUBROUTINE} and not a
682
@code{FUNCTION}.
683
 
684
Expressions that are generated internally (as expansion of a type-bound
685
operator call) may also use additional flags and members.
686
@code{value.compcall.ignore_pass} signals that even though a @code{PASS}
687
attribute may be present the actual argument list should not be updated because
688
it already contains the passed-object.
689
@code{value.compcall.base_object} overrides, if it is set, the base-object
690
(that is normally stored in @code{symtree} and @code{ref} as mentioned above);
691
this is needed because type-bound operators can be called on a base-object that
692
need not be of type @code{EXPR_VARIABLE} and thus representable in this way.
693
Finally, if @code{value.compcall.assign} is set, the call was produced in
694
expansion of a type-bound assignment; this means that proper dependency-checking
695
needs to be done when relevant.
696
 
697
 
698
@c Type-bound operators
699
@c --------------------
700
 
701
@node Type-bound Operators
702
@section Type-bound Operators
703
 
704
Type-bound operators are in fact basically just @code{GENERIC} procedure
705
bindings and are represented much in the same way as those (see
706
@ref{Type-bound Procedures}).
707
 
708
They come in two flavours:
709
User-defined operators (like @code{.MYOPERATOR.})
710
are stored in the @code{f2k_derived} namespace's @code{tb_uop_root}
711
symtree exactly like ordinary type-bound procedures are stored in
712
@code{tb_sym_root}; their symtrees' names are the operator-names (e.g.
713
@samp{myoperator} in the example).
714
Intrinsic operators on the other hand are stored in the namespace's
715
array member @code{tb_op} indexed by the intrinsic operator's enum
716
value.  Those need not be packed into @code{gfc_symtree} structures and are
717
only @code{gfc_typebound_proc} instances.
718
 
719
When an operator call or assignment is found that can not be handled in
720
another way (i.e. neither matches an intrinsic nor interface operator
721
definition) but that contains a derived-type expression, all type-bound
722
operators defined on that derived-type are checked for a match with
723
the operator call.  If there's indeed a relevant definition, the
724
operator call is replaced with an internally generated @code{GENERIC}
725
type-bound procedure call to the respective definition and that call is
726
further processed.
727
 
728
 
729
@c ---------------------------------------------------------------------
730
@c LibGFortran
731
@c ---------------------------------------------------------------------
732
 
733
@node LibGFortran
734
@chapter The LibGFortran Runtime Library
735
 
736
@menu
737
* Symbol Versioning::    Symbol Versioning.
738
@end menu
739
 
740
 
741
@c ---------------------------------------------------------------------
742
@c Symbol Versioning
743
@c ---------------------------------------------------------------------
744
 
745
@node Symbol Versioning
746
@section Symbol Versioning
747
@comment Based on http://gcc.gnu.org/wiki/SymbolVersioning,
748
@comment as of 2006-11-05, written by Janne Blomqvist.
749
 
750
In general, this capability exists only on a few platforms, thus there
751
is a need for configure magic so that it is used only on those targets
752
where it is supported.
753
 
754
The central concept in symbol versioning is the so-called map file,
755
which specifies the version node(s) exported symbols are labeled with.
756
Also, the map file is used to hide local symbols.
757
 
758
Some relevant references:
759
@itemize @bullet
760
@item
761
@uref{http://www.gnu.org/software/binutils/manual/ld-2.9.1/html_node/ld_25.html,
762
GNU @command{ld} manual}
763
 
764
@item
765
@uref{http://people.redhat.com/drepper/symbol-versioning, ELF Symbol
766
Versioning - Ulrich Depper}
767
 
768
@item
769
@uref{http://people.redhat.com/drepper/dsohowto.pdf, How to Write Shared
770
Libraries - Ulrich Drepper (see Chapter 3)}
771
 
772
@end itemize
773
 
774
If one adds a new symbol to a library that should be exported, the new
775
symbol should be mentioned in the map file and a new version node
776
defined, e.g., if one adds a new symbols @code{foo} and @code{bar} to
777
libgfortran for the next GCC release, the following should be added to
778
the map file:
779
@smallexample
780
GFORTRAN_1.1 @{
781
    global:
782
        foo;
783
        bar;
784
@} GFORTRAN_1.0;
785
@end smallexample
786
@noindent
787
where @code{GFORTRAN_1.0} is the version node of the current release,
788
and @code{GFORTRAN_1.1} is the version node of the next release where
789
foo and bar are made available.
790
 
791
If one wants to change an existing interface, it is possible by using
792
some asm trickery (from the @command{ld} manual referenced above):
793
 
794
@smallexample
795
__asm__(".symver original_foo,foo@@");
796
__asm__(".symver old_foo,foo@@VERS_1.1");
797
__asm__(".symver old_foo1,foo@@VERS_1.2");
798
__asm__(".symver new_foo,foo@@VERS_2.0");
799
@end smallexample
800
 
801
In this example, @code{foo@@} represents the symbol @code{foo} bound to
802
the unspecified base version of the symbol. The source file that
803
contains this example would define 4 C functions: @code{original_foo},
804
@code{old_foo}, @code{old_foo1}, and @code{new_foo}.
805
 
806
In this case the map file must contain @code{foo} in @code{VERS_1.1}
807
and @code{VERS_1.2} as well as in @code{VERS_2.0}.
808
 
809
 
810
@c ---------------------------------------------------------------------
811
@c GNU Free Documentation License
812
@c ---------------------------------------------------------------------
813
 
814
@include fdl.texi
815
 
816
 
817
@c ---------------------------------------------------------------------
818
@c Index
819
@c ---------------------------------------------------------------------
820
 
821
@node Index
822
@unnumbered Index
823
 
824
@printindex cp
825
 
826
@bye

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.