[Moon@STONY-BROOK.SCRC.Symbolics.COM: Issue: ADJUST-ARRAY-NOT-ADJUSTABLE (Version 6)]

[Kent M Pitman <KMP@STONY-BROOK.SCRC.Symbolics.COM>]

    Date: 15 Feb 89 08:27 PST
    From: masinter.pa@Xerox.COM
    
    ... it remains that I only have version 6. ... Someone can 
    write Version 7 ...

Ok, you asked for it... This version makes the following changes:

 - It makes adjust array `should signal' rather than `must signal'
   in the array-not-adjustable case. I believe this to be the only
   `consequential' difference between this and version 6.

 - It uses RPG's presentation for the proposal, except for RPG's
   item #4 (Moon's item #1). I've used Moon's presentation style
   but have effectively added RPG's presentation under 
   "Clarifications and Logical Consequences". Hopefully that will
   make things doubly clear.

 - I've moved "the clarifications up above the rationale" so that
   they feel more like an extension of the proposal itself.

 - I've split paragraph 2 of the Rationale into two paragraphs,
   adding a sentence at the end of the new paragraph 2 to help
   address Jeff's perception that we were characterizing error
   detection as an activity without value.

 - Everything else is pretty much left untouched.

-----
Issue:        ADJUST-ARRAY-NOT-ADJUSTABLE
References:   ADJUST-ARRAY (p297), ADJUSTABLE-ARRAY-P (p293),
              MAKE-ARRAY (pp286-289), simple arrays (p28, 289)
Category:     CLARIFICATION/CHANGE
Edit history: 22-Apr-87, Version 1 by Pitman
              15-Nov-88, Versions 2a,2b,2c by Pitman
              02-Dec-88, Version 3 by Pitman
              11-Jan-89, Version 4 by Pitman
              16-Jan-89, Version 5, by Gabriel.  Amended at the meeting to shorten.
              23-Jan-89, Version 6, by Moon.  Shorten without the bug introduced
                        by the amendment, add clarification of SIMPLE-ARRAY type.
	      15-Feb-89, Version 7, by Pitman. Minor changes per comments from
			RPG and Dalton.

Problem Description:

  The description of the :ADJUSTABLE option to MAKE-ARRAY on p288
  says that ``the argument, if specified and not NIL, indicates that
  it must be possible to alter the array's size dynamically after
  it is created. This argument defaults to NIL.''

  The description of the :ADJUSTABLE option does not say what 
  MAKE-ARRAY will do if the argument is unsupplied or explicitly NIL.

  The description of ADJUSTABLE-ARRAY-P on p293 says that it is
  true ``if the argument (which must be an array) is adjustable, and
  otherwise false.'' However, the description of MAKE-ARRAY makes
  it clear that this is not necessarily the same as asking if
  the array was created with :ADJUSTABLE T. If ADJUSTABLE-ARRAY-P
  returns NIL, you know that :ADJUSTABLE NIL was supplied (or no
  :ADJUSTABLE option was supplied), but if ADJUSTABLE-ARRAY-P returns
  T, then there is no information about whether :ADJUSTABLE was used.

  The description of ADJUST-ARRAY on pp297-298 says that it is
  ``not permitted to call ADJUST-ARRAY on an array that was not
  created with the :ADJUSTABLE option.'' This is inconsistent with
  ADJUSTABLE-ARRAY-P.
  
  A problem which comes up in practice is that some programmers
  expect runtime error checking if they have done
  (MAKE-ARRAY ... :ADJUSTABLE NIL) and they later try to adjust
  the array using ADJUST-ARRAY.

  The definition of the SIMPLE-ARRAY type and its subtypes needs
  clarification of its relationship to adjustability.


Proposal (ADJUST-ARRAY-NOT-ADJUSTABLE:CLARIFY):

  1. ADJUSTABLE-ARRAY-P is true of all arrays created with a true
  :ADJUSTABLE option to MAKE-ARRAY.  Whether ADJUSTABLE-ARRAY-P is
  true of some other arrays is unspecified.
 
  2. If MAKE-ARRAY is called with the :ADJUSTABLE, :FILL-POINTER, 
  and :DISPLACED-TO arguments each either unspecified or false, the
  resulting array is a simple array.  (This just repeats what CLtL
  says on page 289, it's here to aid in understanding the next point.)
      
  3. If MAKE-ARRAY is called with one or more of the :ADJUSTABLE,
  :FILL-POINTER, or :DISPLACED-TO arguments true, whether the
  resulting array is simple is unspecified.
      
  4. ADJUST-ARRAY ``should signal'' an error if ADJUSTABLE-ARRAY-P
  of its first argument is false.  ADJUST-ARRAY must not signal an
  `array not adjustable' error if ADJUSTABLE-ARRAY-P of its first
  argument is true.

  5. The value of ADJUSTABLE-ARRAY-P on a simple array is unspecified.

  Note: ``should signal'' is taken from the new error terminology.
  It means that in ``safe code'' (code compiled with highest safety)
  an error must be signalled, but that in unsafe code (code not compiled
  with highest safety), an error might or might not be signalled.

Clarifications and Logical Consequences:

  a. Whether an array can be both simple and adjustable is unspecified.

  b. There is no specified way to create an array for which ADJUSTABLE-ARRAY-P
     definitely returns NIL.

  c. There is no specified way to create an array that is non-simple.

  d. This legitimizes ADJUSTABLE-ARRAY-P as an appropriate predicate to
     determine whether ADJUST-ARRAY will reliably succeed.

  e. If ADJUST-ARRAY is invoked on an array that was created without
     supplying :ADJUSTABLE true, an `array not adjustable' error
     ``should be signalled'' unless ADJUSTABLE-ARRAY-P returns true on
     that array (in which case it must not signal an `array not adjustable'
     error).

Rationale:

  This effectively makes the status quo explicit.  This preserves the
  raison d'etre of simple arrays, which is to provide a portable interface
  to implementation-dependent specialized arrays that trade decreased
  functionality for faster access.

  Specifying the points left unspecified (requiring all simple arrays to be
  non-adjustable and all adjustable arrays to be non-simple) would require
  large changes to some implementations and would be of little benefit to
  users, merely making one kind of nonconforming program fail in all
  implementations instead of failing only in some implementations. The 
  argument here is not that the error checking would not be useful for
  developers of portable code, but only that the cost of introducing that
  error checking would be exceedingly high for some implementations.

  Users need to know that certain arrays are simple, so they can put in
  declarations and get higher performance, but users have no need to be
  able to create arrays that are definitely non-simple (for lower
  performance) or definitely non-adjustable (to cause errors).

Examples:

  1. The following program is conforming.  It is unspecified which branch
  of the IF it follows.
  
    (defun double (a)
       (if (adjustable-array-p a)
           (adjust-array a (* (length a) 2))
           (let ((new (make-array (* (length a) 2))))
             (replace new a :end1 (length a))
             new)))
  
    (double (make-array 30))

  2. The following program is conforming.  In no implementation is the
  type declaration violated.

    (let ((a (make-array 100)))
      (declare (simple-array a))
      (frob a))


Current Practice:

  Probably everyone is compatible with this proposal. 

  Symbolics Genera makes :ADJUSTABLE NIL arrays adjustable in most cases,
  and ignores adjustability in deciding whether an array is simple,
  and is compatible with this proposal.

  Lucid, IIM, and Symbolics Cloe make :ADJUSTABLE NIL arrays non-adjustable
  in all cases, and make all arrays non-simple unless the Common Lisp
  language requires them to be simple, and are compatible with this proposal.

Cost to Implementors:

  It's in principle possible that some implementation would have to change,
  but in practice there are no known implementations that would have to change.

Cost to Users:

  None. This is a fully compatible change from the user's standpoint.

Benefits:

  Users would know what to expect.

Non-Benefits:

  Users who expect adjusting arrays created with :ADJUSTABLE NIL to signal
  an error would not get the desired error checking.

Aesthetics:

  Most people believe the status quo is unaesthetic.  Having an aspect of
  the language explicitly unspecified is more aesthetic than having it
  implicitly unspecified on account of vague or inconsistent documentation.

Discussion:

  MACSYMA ran into portability problems due to the status quo.
  If the issue had been documented, that would have helped.
  Encouraging implementations that are able to at least make
  (MAKE-ARRAY ... :ADJUSTABLE NIL) create non-adjustable arrays
  where possible would help, too.

  We considered proposals to incompatibly change this primitive in a
  variety of ways, but the community was very split with strong proponents
  and opponents of each alternate proposal.

  The overriding concern driving this proposal is that Symbolics 
  has asserted that most of the other really interesting proposals would
  likely involve a sizable cost to implementors (and their installed bases)
  to implement what were judged by some as gratuitous changes from the
  status quo.

  Pitman wishes some of the other proposals were economically feasible to
  pursue but reluctantly agrees that maintaining (and clearly documenting)
  the status quo is probably the most reasonable avenue left to us.