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 verion of N1820, "C Interoperability Objectives", with references to the TR draft N1xxx (J3/10-251), specifying where each of the Requirments 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 sepcified 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 mement.*******] 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.]