To: J3 10-142r2 From: Bill Long Subject: C Interoperability Objectives Date: 2010 February 19 References: J3/05-159, J3/06-171r1, N1761.txt, N1808.pdf 1. Introduction --------------- The purpose of TR 29113 is: C interoperability in the Fortran Standard provides for the sharing of some forms of data between Fortran and C. However, it does not address procedures that have data pointer, allocatable, assumed- shape, or optional dummy arguments. This work item aims to develop ways and means, using facilities provided by the companion Fortran processor, to allow C functions to handle such Fortran dummy arguments directly. This has been extended by the addition of assumed-type and assumed-rank arguments. Constraints on those are mentioned later. The TR does not have further extensibility as an objective, except as explicitly mentioned. 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. 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. 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. 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. 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. 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). Requirement 5: A mechanism to inquire the rank of an assumed-rank object shall be provided. 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. 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. 2.4 Optional Arguments ---------------------- Requirement 7: Interoperable interfaces should allow OPTIONAL dummy arguments. Constraint 4: Dummy arguments with both the OPTIONAL and VALUE attributes are not required to be interoperable. 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. (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. 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. 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. Array strides of zero and overlapping elements are not supported. 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. 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. 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. 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. 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. b) C should be able to allocate memory for POINTER arrays, starting from C pointers, and pass them to Fortran as such. Constraint 6: Neither Fortran nor C may deallocate pointers associated with a target by the other. 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. b) Minimize the work required to modify the Fortran compiler. 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. b) Expand the uses of assumed-rank objects within Fortran.