To: J3                                                     10-205
From: Bill Long
Subject: Interop TR: Version numbers
Date: 2010 September 09
Reference: 10-165r2.pdf, 10-203

Discussion:

A Version number scheme was suggested as a means for implementations
to detect possible incompatible changes to the header file and
descriptor contents. A Version Number would be included in the header
file as a macro that expands to an integer constant.  Similarly, a
Version member is added to the C descriptor.  If a user-written
function, or one of the supplied intrinsic functions, determines that
the version number in a C descriptor does not match the corresponding
Version in the header file included when the function was compiled, an
error can be issued.  This facility allows for possible future changes
to the C descriptor definition by providing a means of detecting when
incompatible descriptor definitions are being used.

As an example, a function is compiled with an 'old' header file
included, but gets linked into a code that is compiled with a 'new'
header file included.  If the new C descriptor version is not an
upward compatible extension of the old one, the memory reference
offsets into the descriptor in the old function might be wrong for the
format of the descriptor being passed to the function.  This is not an
issue for a set of user files that are all re-compiled
together. However, it could be an issue for a collection of library
routines that are archived and later linked into new codes.

Edits to 10-165r2:

[9:9] In the first edit in paper 10-203, add "CFI_version_t" to the
list of new typedefs defined in ISO_Fortran_binding.h.

[9:36+] Add a new member to the C descriptor struct:

"CFI_version_t version; equal to the value of CFI_VERSION in the
ISO_Fortran_binding.h header file that was accessible when this
descriptor was created. CFI_version_t shall be a typedef identifier
for a standard integer type capable of representing the values used
for header file versions. This member shall be defined when the
descriptor is created and shall not be subsequently redefined."


[10-23+] Add a new paragraph after p2 of 5.2.5 Macros:

"CFI_VERSION - the version of the ISO_Fortran_binding.h header file
containing this macro. Two instances of ISO_Fortran_binding.h that
have corresponding structure, prototype, typedef, or macro definitions
that are incompatible shall have different values for CFI_VERSION."