To: J3                                                     10-205r2
From: Bill Long
Subject: Interop TR: Version numbers
Date: 2010 October 11
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.

This feature is useful only if the location and format of the version
field is fixed in the descriptor. Otherwise a program compiled with a
new header file would not be able to find the version in an old
descriptor. This requires that the layout of the members of the cdesc
scruct be more constrained.

Edits to 10-165r2:


[9:19-20] In the second sentence of 5.2.2 CFI_cdesc_t, para 1, replace
"in any order:" with ".". Then add two new sentences: "The first three
members of the struct shall be base_addr, elem_len, and version in
that order, the final member shall be dim, with the other members
after version and before dim in any order."

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

"int version; equal to the value of CFI_VERSION in the
ISO_Fortran_binding.h header file that defined the format and meaning
of this descriptor. This member shall be defined when the descriptor
is created and shall not be subsequently redefined."


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

"CFI_VERSION - an integer constant that encodes 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."

   "NOTE 5.0+
   The intent is that the version should be increased every time that
   the header is extended, and that the version in a descriptor may
   be used to provide a level of upwards compatibility, by using
   means not defined by this Technical Report."