10-253
To: J3
From: Bill Long
Subject: Interop TR: Updated version of N1820
Date: 2010 October 14
Reference: 10-165r2.pdf
1. Introduction
---------------
This paper consists of an annotated version of N1820, "C
Interoperability Objectives", with references to the TR draft N1xxx
(J3/10-251), specifying where each of the Requirements and Constraints
is addressed. Reply text is enclosed in [ ].
[In the initial version of this paper, references are to section
numbers in 10-165r2 and J3 meeting paper numbers. The final version
will be updated to reflect section numbers of the revised TR draft.]
2 Requirements
--------------
2.1 General
-----------
Requirement 1:
A mechanism should be provided to enable a C programmer to
conveniently obtain the address of a particular element within an
assumed-rank, assumed-shape, allocatable, or pointer array.
[Paper J3/10-222r1.]
Requirement 2:
If it is reasonably feasible, a mechanism should be provided for
C function to specify by explicit declaration the type or rank
(both preferred) of an assumed-shape, allocatable, or pointer
object. The objective is to provide a facility for type and rank
safety.
[Paper J3/10-224r2]
Constraint 1:
It is generally the case that assumed-shape, allocatable, and
pointer objects are represented in implementations as a
descriptor. It is reasonable to assume the same will be true of
assumed-rank objects. The descriptor used within Fortran to
describe an object should not be visible to the C function that
has access to the corresponding object in a C function.
[The TR specifies a C descriptor in 5.2.2. References to a Fortran
descriptor were removed.]
2.2 Assumed-type
----------------
Requirement 3:
A dummy argument declared assumed-type should be compatible with
an actual argument of an arbitrary interoperable type, or of
assumed-type. It is not required that the interface for the
procedure specify bind(c). A mechanism to inquire the type of an
assumed-type dummy argument in a C function is not required.
[The assumed-type feature is specified in 2.1, with the argument
association rules in 3.3.]
Constraint 2:
Assumed-type dummy arguments may appear as actual arguments. Apart
from that, such dummy arguments are usable only in a procedure
which can access them with the type of the ultimate argument that
is not assumed-type. There is no intent to provide such a
mechanism for this use in Fortran. An explicit interface is
required for a procedure with an assumed-type dummy argument.
[Specified in 2.1, 3.2, and 3.3.]
2.3 Assumed-rank
----------------
Requirement 4:
A dummy argument declared assumed-rank should be compatible with
an actual argument of an arbitrary rank, or of assumed-rank. It is
not required that the interface for the procedure specify bind(c).
[Specified in 3.3]
Requirement 5:
A mechanism to inquire the rank of an assumed-rank object shall be
provided.
[For Fortran, the RANK intrinsics is specified in 4.2. For C, the rank
member of the C descriptor (5.2.2) specifies the rank.]
Requirement 6:
A mechanism to inquire the bounds and strides in each dimension of
an assumed-rank array shall be provided to a C function. An
assumed-rank array is not required to be contiguous.
[The C function CFI_cdesc_to_bounds (5.2.6.6) produces the bounds and
strides information.]
Constraint 3:
Assumed-rank dummy arguments may appear as actual arguments. Apart
from that, such arguments are usable if passed to a procedure
which can access them with the correct rank. There is no intent to
provide such a mechanism for this use in Fortran. The interface
of a procedure called with an actual argument that is assumed-rank
shall be explicit. An explicit interface is required for a
procedure with an assumed-rank dummy argument.
[Specified in 2.2, 3.2, and 3.3.]
2.4 Optional Arguments
----------------------
Requirement 7:
Interoperable interfaces should allow OPTIONAL dummy arguments.
[Specified in 2.3.]
Constraint 4:
Dummy arguments with both the OPTIONAL and VALUE attributes are
not required to be interoperable.
[Specified in 2.3.]
2.5 Assumed-shape Arrays
------------------------
Requirement 8:
(a) An interface with bind(c) may include assumed-shape dummy
arguments. The called procedure should be able to access the
shape, strides, and elements of the dummy argument.
[Interoperability of interfaces in specified in 5.2.8. Access
mechanisms are specified in 5.2.2 and 5.2.6.]
(b) A C function should have a mechanism to create an array that
it can use as an actual argument corresponding to an assumed-shape
dummy of a Fortran procedure. The same mechanism should allow an
existing block of memory in the C function, including an array
passed into the C function, or memory accessed as a global object,
to be passed to an assumed-shape dummy in Fortran.
[Paper 224r2]
c) In the scope of a C function, the lower bounds of an
assumed-shape dummy argument are assumed to be zero. In a Fortran
procedure, the lower bounds of an assumed-shape dummy are assumed
from its declaration.
[******* John had listed this as "OK", but I'm not seeing the words
at the moment.*******]
Constraint 5:
The memory that is associated with a Fortran assumed-shape dummy
argument should be memory that is accessible in Fortran using
normal variable definitions or references.
[Implied by 5.2.8.]
Array strides of zero and overlapping elements are not supported.
[******* I do not see specific prohibitions for this. ******]
2.6 Allocatable Objects
-----------------------
Requirements 9:
a) The requirements and constraints that apply to assumed-shape
arrays also apply to ALLOCATABLE ones (including converting
them to assumed-shape), excluding the interpretation of lower
bounds of an assumed-shape array.
[******* John listed this as "OK", but I don't see it spelled out.
With the new functions provided in 10-224r2, it is
straightforward to create a new assumed-shape descriptor
for the object. ********]
b) A mechanism should be provided for a C function to allocate and
deallocate ALLOCATABLE objects passed from Fortran. The
mechanism should provide a means for the C function to specify
the bounds for array being allocated.
[Specified by 5.2.6.2 and 5.2.6.3 (CFI_allocate and CFI_deallocate).]
c) A mechanism should be provided for a C function to create an
ALLOCATABLE object that can be passed as an actual argument to
Fortran corresponding to an ALLOCATABLE dummy argument. Such
an ALLOCATABLE object should be capable of allocation and
deallocation using Fortran ALLOCATE and DEALLOCATE statements.
[Specified by 5.2.6.2.]
d) INTENT(OUT) ALLOCATABLE dummy arguments are permitted in a
BIND(C) routine. It is the responsibility of the processor to
deallocate the actual argument in any cross-language call. It
is not required for the processor to handle this in C-to-C
calls.
[Paper 225r1]
2.6 Pointer Arrays
------------------
Requirements 10:
a) all of the requirements and constraints that apply to
ALLOCATABLE arrays, except as noted in the following
requirement, also apply to POINTER ones.
[Implied by 5.2.6.2 and 5.2.6.3.]
b) C should be able to allocate memory for POINTER arrays,
starting from C pointers, and pass them to Fortran as such.
[Specified in 5.2.7.]
Constraint 6:
Neither Fortran nor C may deallocate pointers associated with a
target by the other.
[Subsequent discussion leads to this being an already solved issue,
and the requirement needs to be reworded to refer to allocation rather
than association. This needs to be added to the N1820 reply document.]
3 Goals
-------
These are not part of the requirements, but might affect the
implementation model.
a) Execution efficiency is important, which definitely means that
data remapping should not be needed, but it is unclear beyond
that.
[It appears that data remapping is avoided, though descriptor
reformatting is required which has some performance impact.]
b) Minimize the work required to modify the Fortran compiler.
[Arguably, we failed at this, but it was not a requirement.]
4 Features not included
-----------------------
In the discussion of the requirements for the TR, additional
requirements were suggested, but failed to achieve sufficient
consensus to be included in the TR. These might be considered as part
of a future standard. They are:
a) Make assumed-length character an interoperable type.
[Subsequently addressed in Paper 237r1.]
b) Expand the uses of assumed-rank objects within Fortran.
[Not addressed.]