To: J3                                                     11-133
From: R. Bader
Subject: Changes to the CFI_associate function
Date: 2011 January 28
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) Add a NOTE discouraging certain kinds of descriptor modifications.


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. Otherwise, the descriptor is not modified,
        and the function result is CFI_ERROR_BASE_ADDR_NULL."

[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)"

[16:18+] Add

       "NOTE 5.3++:
        It is recommended that this method should - for the sake of
        clarity - not be used in case the descriptor is for an
        assumed shape entity created by the Fortran processor,
        because then the descriptor becomes unrelated to the
        original Fortran object."