To: J3                                                     11-133r1
From: R. Bader
Subject: Changes to the CFI_associate function
Date: 2011 January 30
References: N1838, N1844

INTRODUCTION:

The following changes to the CFI_associate function are suggested:

(1) remove the implicit invocation of malloc(); dynamic creation of
    memory for Fortran objects should always be done using
    CFI_allocate, or by explicitly invoking malloc() previous
    to a call to CFI_associate(). This is also more consistent with
    what is stated in 5.2.7

(2) For descriptors whose attribute member has the value
    CFI_attribute_pointer, passing a NULL base address nullifies
    the pointer.

(3) Move discussion of memory requirements to a NOTE

(4) Prohibit application to dummy arguments


EDITS to N1838:

Section 5.2.6:

[15:12] Correct typo: replace "void *, base_addr" by "void * base_addr"

[15:14-19] Replace "If the object ... returned by malloc." by

       "The base_addr parameter may be a non-NULL pointer to a
        memory area large enough to provide storage for the object.
        If the attribute member has the value CFI_attribute_pointer,
        a NULL pointer may be passed, which causes the bounds[]
        parameter to be ignored and the pointer entity to become
        disassociated. A NULL pointer shall not be passed unless
        the attribute member has the value CFI_attribute_pointer."

[15:20] Replace "If memory allocation ... fails, " by "If"

[15:23+] Add

       "NOTE 5.3+:

        The amount of storage required to make the pointer entity well
        defined is determined by the elem_len member of the descriptor
        and the bounds[] argument of the function call. For a rank zero
        entity, the bounds[] argument is disregarded. The storage
        area may have been created by a previous call to malloc(), or
        may have been statically declared. There is no way for
        the function call to determine whether a sufficient amount of
        memory has been made available to the object."

Section 5.2.7

[16:16] After "with a data pointer", add "or assumed-shape entity"
        After "in a C descriptor", add " (5.2.6.5). Such a C
        descriptor shall not represent a dummy argument."