#

## Issue RESULT-LISTS-SHARED Writeup

    Issue:        RESULT-LISTS-SHARED
    Forum:	      Editorial
    References:   DIRECTORY (p427), LIST-ALL-PACKAGES (p184)
    Category:     CLARIFICATION
    Edit history: 02-Mar-91, Version 1 by Pitman
    	      15-Mar-91, Version 2 by Pitman (repair current practice)
    Status:	      For X3J13 consideration

    Problem Description:

      CLtL does not specify whether the list returned by each of these
      functions is freshly-consed each time, or whether it must be treated
      as immutable: LIST-ALL-PACKAGES, DIRECTORY.

    Proposal (RESULT-LISTS-SHARED:SPECIFY):

      Specify that the lists returned by LIST-ALL-PACKAGES and DIRECTORY are
      freshly consed on every call.  The list resulting from calls to these
      functions may therefore be freely modified by the caller.

    Example:

      ;Example of recycling list structure from LIST-ALL-PACKAGES
      (DEFUN ALIST-ALL-PACKAGES ()
        (LET ((P (LIST-ALL-PACKAGES)))
          (DO ((L P (CDR L)))
    	  ((NULL L) P)
    	(SETF (CAR L)
    	      (LIST* (CAR L)
    		     (PACKAGE-NAME (CAR L))
    		     (PACKAGE-NICKNAMES (CAR L)))))))

      ;Example of recycling list structure from DIRECTORY
      (DEFUN FULL-DIRECTORY (SPEC)
        (LET ((D (DIRECTORY SPEC)))
          (DO ((L D (CDR L)))
              ((NULL L) D)
            (SETF (CAR L)
     	      (LIST (CAR L)
    		    :AUTHOR (FILE-AUTHOR (CAR L))
    		    :WRITE-DATE (FILE-WRITE-DATE (CAR L))
    		    :LENGTH (IGNORE-ERRORS
    			      (WITH-OPEN-FILE (S (CAR L))
    				(FILE-LENGTH S))))))))

    Rationale:

      In most implementations, packages are stored in a hash table for
      faster access by the reader, so the list returned by LIST-ALL-PACKAGES
      is probably freshly consed already.  Also, LIST-ALL-PACKAGES is
      probably called sufficiently seldom that there is no serious
      efficiency issue here.

      In most implementations, information about the file system is external
      to Lisp and must be freshly computed each time a directory listing is
      done anyway.  Better not to force the caller to do a COPY-LIST on a
      call when the list can easily be guaranteed to be fresh to begin with.

      Even in situations where it was possible to return a
      non-freshly-consed list, this might put internal data structures of
      the implementation at risk for no really good efficiency reason.

    Current Practice:

      Symbolics Genera freshly conses the list returned by DIRECTORY.
      Symbolics Genera does not freshly cons the list returned by LIST-ALL-PACKAGES.

    Cost to Implementors:

      Very small.

    Cost to Users:

      None.

    Cost of Non-Adoption:

      Users wouldn't know what to expect and would be forced to do a
      COPY-LIST just to be sure when they planned to modify the result.  If
      they forgot, and the implementation decided to return a
      non-freshly-consed list, an attempt to modify that list might
      compromise the integrity of the running Lisp.

    Benefits:

      Clearer specfication

    Aesthetics:

      Negligible effect.

    Discussion:

      Pitman supports this proposal.  (He's more than once wanted to modify
      the result list of DIRECTORY and had to do a gratuitous COPY-LIST just
      to be safe.)

Copyright 1996-2005, LispWorks Ltd. All rights reserved.