MCL 4.1 & 3.2 release notes
===========================

Thank you for using MCL 4.1 and/or MCL 3.2. This document describes
what has changed since MCL 4.0 and MCL 3.1.

Please send bug reports and other feedback to bug-mcl@digitool.com.
Digitool's web page is <http://www.digitool.com/>.

For MCL related discussion, subscribe to info-mcl@digitool.com
by sending a message to info-mcl-request@digitool.com whose
body contains the single word: subscribe.


Installation
============

Install MCL 4.1 & 3.2 by dragging their respective folders to your hard disk.
For more details, see the Getting Started with MCL book, which is on the CD in
Acrobat format and available in paper form from Digitool as part of the MCL
hardcopy documentation product.


Known Incompatibilities
=======================

MCL 4.1 is incompatible with some versions of the "PPCExceptionEnabler" that
shipped with MCL 3.9. IF YOU HAVE "PPCExceptionEnabler" IN YOUR SYSTEM
EXTENSIONS FOLDER, GET RID OF IT. It was necessary for using some debuggers
with MCL 3.9, but is not necessary for MCL 4.0 and will cause confusing
behavior from MCL 4.1. If you need to run both MCL 3.9 and MCL 4.1 based
applications on the same machine, Digitool has a version of the
"PPCExceptionEnabler" that does not have this incompatibility. To get it, send
mail to bug-mcl@digitool.com.


New features - 4.1 & 3.2
========================

A first implementation of a dynamic-priority scheduler is in
"ccl:library;new-scheduler.lisp". The new scheduler prevents a high
priority runnable process from completely locking out a lower priority
runnable process. More details in the file. We were hesitant to make
this part of the shipping lisp until it gets lots of testing. Please
try it and give us feedback.

process-poll & process-poll-with-timeout are like process-wait and
process-wait-with-timeout except the predicate can call process-poll
or process-wait without causing the scheduler to malfunction. Since
the predicate is always called in the polling process, using process-poll
slows things down a bit. If your predicate absolutely must use
process-wait, however, this works around that necessity.

MCL now reads and writes the :|styl| scrap. This makes copy and paste
pass font & color information to and from other applications that
support styled scraps (most of them do). This feature can be disabled
by setting *use-external-style-scrap* to NIL.

MCL has default handlers for the AppleEvents generated by the AppleScript
commands "launch application ..." and "tell application ... to activate".

There is a new Fred command, meta-j, which toggles between:
  1) a click in fred window sets the keyscript to the script of the
     neighboring font.
  2) a click in fred window leaves the keyscript unchanged.
The initial behavior is 1) above.

Another new Fred command, ctrl-x ctrl-p, finds the first unbalanced paren
or #| or |# in the buffer.

There is a new "Create Bug Report" menu item on the "Tools" menu
right below the "Backtrace" menu item. It is enabled if any process
is in a break loop. It creates a bug report template containing
information that will be helpful to us in analyzing your report.
You can simply fill in information about how to cause the bug,
copy the report, paste it into your email program, and send it
to us.


New features - 4.1 only
=======================

MCL 4.1 now has direct support for Open Transport TCP streams. The implementation
is in the files "ccl:library;opentransport.lisp" and "ccl:library;io-buffer.lisp".
The OpenTransport code requires the "OpenTransportSupport" shared library to
be in the MacOS shared library search path; it or an alias to it must be either
in the system extensions folder or in the same folder as the MCL application.
MCL 4.1 is shipped with this library in the "ccl:" directory.

The control stack is now segmented. This means that all stack overflow
errors are continuable if there is enough memory. The temp & value
stacks are (as in 4.0) allocated from multi-finder temporary memory
unless there is not enough of it in which case they come from the Mac
heap. The control stack is always allocated from the Mac heap (this is
a limitation of the Macintosh thread manager). Each stack group has
its own minimum stack size before an error is signalled, but no stack
group will signal a stack overflow error unless its stack size is
greater than *minimum-stack-overflow-size*. This gives you an easy way
to prevent stack overflow errors system-wide while allowing individual
stack groups to have even larger stacks.

MCL 4.1 CLOS now supports a Dylan-like primary class mechanism. A primary
class'es slots are always guaranteed to be at the same position. This
enables compiler optimizations to speed up calls to slot-value and
slot accessor generic functions. Two primary classes cannot be mixed
(unless they both have the same slot names in the same order).

MCL 4.1 now has two sizes of floats. The lisp type short-float is an IEEE
single float (32 bits). The lisp types single-float, double-float, and
long-float all denote an IEEE double float (64 bits). We decided to
call the IEEE 32-bit float a short-float to prevent the need for you
to change your code; the lisp type single-float, which is an IEEE
64-bit float, is the default for all floating point coercions and the
reader. Unlike in MCL 3.x, MCL 4.1 short-float's are not immediates.
Hence, short-float math conses. It conses only half as much as
double-float math, however. We hope to have better support for unboxed
floating point operations in a future version of MCL.


Changes - 4.1 & 3.2
===================

MCL's table-dialog-item implementation no longer uses the Macintosh
list manager. This makes it faster and eliminates size limitations. It
also has two additional features: variable column widths & row heights
and the ability to draw separator lines between the cells. The API is
upwardly compatible with the old implementation.

To support tables with huge numbers of elements, MCL's points are no
longer restricted to 16 bits in each dimension. Points with dimensions
that won't fit in 16 bits are represented as conses. All the point
functions (e.g. make-point, point-h, point-v) are updated to accept
conses as points.

The 68K and PPC implementations now share most of their source code.
This means that the "Additional MCL Source Code" folder on the CD will
not have separate sub-folders for MCL 3.2 & MCL 4.1. Differences are
denoted by sub-folders of "lib" & "level-1" named "ppc" and "68k" plus
read-time conditionalizations based on the :ppc-target feature.

(toplevel) no longer does a process-preset. Instead it throws to the
ccl::process-reset-tag with a kill arg of :toplevel. This is
recognized by the process code as a request to throw to toplevel and
restart. This runs unwind-protect cleanup forms. They didn't run
before.

file-data-size, file-resource-size, file-allocated-data-size,
file-allocated-resource-size, & file-info are now exported. They have
been in the printed documentation for a long time.

The file "ccl:examples;config.lisp" has been removed. The
config-info function that used to be defined by that file is now
part of the shipping MCL image. It is used for the "Create Bug
Report" menu item.


Changes - 4.1 only
==================

The fasl version has been changed, but the minimum fasl version is the
same. This means that PFSL files compiled with MCL 4.0 will still work
in MCL 4.1, but PFSL files compiled with MCL 4.1 will error if loaded
into MCL 4.0.

The cfrg name of the "pmcl-kernel-4.1" file is different than the one
for "pmcl-kernel-4.0". This means that neither MCL 4.0 nor 4.1 will
work with the other's kernel. More importantly, applications built
with MCL 4.0 and MCL 4.1 can run at the same time from the same
directory.

%get-single-float and %hget-single-float now return a
short-float. (setf %get-single-float) and (setf %hget-single-float)
require a short-float as the new value.

It is possible to abort out of a looping event processing function
with command-option-period. This has always worked in MCL 3.x, but was
broken in earlier 4.x versions.


Optimizations - 4.1 & 3.2
=========================

Fixed some really bad inefficiencies having to do with string
comparisons when the system script is Japanese. In particular these
changes improve the response to a click in the menubar.


Optimizations - 4.1 only
========================

The garbage collector is about 5% faster.

Multiply of bignums is about twice the speed of 4.0.
Consing is the same.


Symbols newly exported from the CCL package - 4.1 & 3.2
=======================================================

  activate-application-handler
  launch-application-handler
  file-data-size
  file-resource-size
  file-allocated-data-size
  file-allocated-resource-size
  file-info
  *use-external-style-scrap*
  *minimum-stack-overflow-size*
  *super-optimize-primary-slot-access*
  separator-color
  separator-pattern
  separator-size
  separator-visible-p
  table-column-width
  table-row-height


New functions & variables - 4.1 & 3.2
=====================================

activate-application-handler application theAppleEvent reply handlerRefcon  [ generic function ]
activate-application-handler (application t t t)                            [ method ]
  Called to handle the 'misc' 'actv' AppleEvent, which is generated by
the AppleScript command: "tell application ... to activate". The default
method calls #_SetFrontProcess to bring MCL to the front.

launch-application-handler application theAppleEvent reply handlerRefcon    [ generic function ]
launch-application-handler (application t t t)                              [ method ]
  Called to handle the 'ascr' 'noop' AppleEvent, which is generated by
the AppleScript command: "launch application ...". The default method
does nothing.

*use-external-style-scrap*                                                  [ variable ]
  If true, the default, MCL will read and write the :|styl| scrap to copy
font and color information to and from other applications.

separator-color table                                                       [ generic function ]
separator-color (table-dialog-item)                                         [ method ]
(setf separator-color) color table                                          [ generic function ]
(setf separator-color) (t table-dialog-item)                                [ method ]
(setf separator-color) :around (t table-dialog-item)                        [ method ]
:separator-color                                                            [ initarg ]

separator-pattern table                                                     [ generic function ]
separator-pattern (table-dialog-item)                                       [ method ]
(setf separator-pattern) pattern table                                      [ generic function ]
(setf separator-pattern) (t table-dialog-item)                              [ method ]
(setf separator-pattern) :around (t table-dialog-item)                      [ method ]
:separator-pattern                                                          [ initarg ]

separator-size table                                                        [ generic function ]
separator-size (table-dialog-item)                                          [ method ]
(setf separator-size) size table                                            [ generic function ]
(setf separator-size) (t table-dialog-item)                                 [ method ]
(setf separator-size) :around (t table-dialog-item)                         [ method ]
:separator-size                                                             [ initarg ]

separator-visible-p table                                                   [ generic function ]
separator-visible-p (table-dialog-item)                                     [ method ]
(setf separator-visible-p) visible-p table                                  [ generic function ]
(setf separator-visible-p) (t table-dialog-item)                            [ method ]
(setf separator-visible-p) :around (t table-dialog-item)                    [ method ]
:separator-visible-p                                                        [ initarg ]

These control the separator lines drawn between table cells. The default is
not to draw separator lines. separator-size is a point giving the size of the
pen that is used to draw the separator lines. The default is #@(0 0).
separator-color is an MCL color as returned by make-color or as stored in
*red-color*, *blue-color*, etc. The default is *gray-color*. separator-pattern
is either a pattern as stored in *black-pattern*, *white-pattern*, etc., a
symbol whose symbol-value is such a patter, or a function of no arguments that
returns a pattern. The default is '*black-pattern*. separator-visible-p is a
boolean. The default is t. The :around methods on the setf generic functions
are responsible for invalidating the table so that it will be redrawn. The
other methods are slot accessor methods generated by the defclass for
table-dialog-item.

Note that if you set the separator-pattern to a pattern macptr, and you
need to use this table instance after a save-application, you will need
to reinitialize the pattern with a def-load-pointers function.

table-row-height table row                                                  [ generic function]
table-row-height (table-dialog-item t)                                      [ method ]
(setf table-row-height) height table row                                    [ generic function ]
(setf table-row-height (t table-dialog-item t)                              [ method ]

table-column-width table row                                                [ generic function]
table-column-width (table-dialog-item t)                                    [ method ]
(setf table-column-width) height table row                                  [ generic function ]
(setf table-column-width (t table-dialog-item t)                            [ method ]

  These control the variable row heights and column widths for
table-dialog-item's. The default row width for a table is
(point-v (cell-size table)). The default column width is
(point-h (cell-size table)). These functions change particular
rows and columns from the default.


New functions and variables - 4.1 only
======================================

:primary-p                                                                  [ DEFCLASS class option ]
*super-optimize-primary-slot-access*                                        [ variable ]
  These control the new primary class feature. A true value to the
:primary-p class option in a DEFCLASS form declares that the class is
primary. This class'es slots are to be stored first in all instances.
If the compiler knows that a variable is an instance of a primary
class it will optimize calls to slot-value and accessor functions of
the primary class. This optimization is normally safe, i.e. the generated
code will work correctly even if the class is redefined and even if the
definition makes the class no longer primary (the latter will turn
the optimization into a pessimazation, however). If safety is inhibited,
either via the compiler policy or by (declare (speed 3) (safety 0)), and
*super-optimize-primary-slot-access* is true, then the generated code will
be even faster, but will NOT be correct if the class or any of its superclasses
are changed in a way that moves any instance's slots.


Bug fixes
=========

Too numerous to list.


Known bugs
==========

On some Powerbooks at least a process doing (loop) will hang the
machine.

If you have an extension installed that changes the default menu
background color to something other than white, MCL will still
draw the "Edit/Font Color" menu background in white.


Primary Classes - 4.1 only
==========================

Primary classes are defined via a true value for the :PRIMARY-P
class option to DEFCLASS. The value IS evaluated. All
instances of a primary class or one of its subclasses have
the slots that are in the primary class at a fixed offset.
This means that you can't multiply inherit two primary
classes unless one of them is a subclass of the other one.
This property allows a compiler optimization. The optimization
is enabled for slot-value and slot accessors if the instance
is known at compiler time to be an instance of a primary class
(or one of its subclasses) and the slot is known at compiler
time to be a slot of that class.

Normally, the optimization generates code that will work correctly
even if the class is redefined to not be primary and/or the slot
position moves and/or another method is installed or removed on a
slot accessor generic function. If ccl:*super-optimize-primary-slot-access*
is true and ccl::nx-inhibit-safety-checking returns true (normally this
means speed 3, safety 0), then it generates super-fast code that
will NOT work correctly if any slots are added to the instance's
class or if the primary slot moves. The super-fast code also does
NOT check for unbound slots.

Note that for the optimizations to kick in the class must
be known to be primary at compile time. Since MCL doesn't
store that information about classes in the compile time
environment, this means that the class definition must have
been already evaluated; it is not enough to just appear earlier
in the file than the form to be optimized (unless you load the
file before compiling it).

MCL's compiler is not yet smart enough to know that a specialized
argument to a method is of the specializer type (unless it is modified).
This would be a good thing to add.

Example:

? (defclass foo ()
    ((x :accessor foo-x :initarg :x))
    (:primary-p t))
#<STANDARD-CLASS FOO>
? (let ((foo (make-instance 'foo :x 1)))
    (without-interrupts
     (time (dotimes (i 1000000)
             (slot-value foo 'x)))))
(DOTIMES (I 1000000) (SLOT-VALUE FOO 'X)) took 679 milliseconds (0.679 seconds) to run.
NIL
? (let ((foo (make-instance 'foo :x 1)))
    (declare (type foo foo))
    (without-interrupts
     (time (dotimes (i 1000000)
             (slot-value foo 'x)))))
(DOTIMES (I 1000000) (SLOT-VALUE FOO 'X)) took 285 milliseconds (0.285 seconds) to run.
NIL
? (let ((foo (make-instance 'foo :x 1)))
    (declare (type foo foo)
             (optimize (speed 3) (safety 0)))
    (without-interrupts
     (time (dotimes (i 1000000)
             (slot-value foo 'x)))))
(DOTIMES (I 1000000) (SLOT-VALUE FOO 'X)) took 278 milliseconds (0.278 seconds) to run.
NIL
? (setq *super-optimize-primary-slot-access* t)
T
? (let ((foo (make-instance 'foo :x 1)))
    (declare (type foo foo)
             (optimize (speed 3) (safety 0)))
    (without-interrupts
     (time (dotimes (i 1000000)
             (slot-value foo 'x)))))
(DOTIMES (I 1000000) (SLOT-VALUE FOO 'X)) took 16 milliseconds (0.016 seconds) to run.
NIL
? (setq *super-optimize-primary-slot-access* nil)
NIL
? (let ((foo (make-instance 'foo :x 1)))
    (without-interrupts
     (time (dotimes (i 1000000)
             (foo-x foo)))))
(DOTIMES (I 1000000) (FOO-X FOO)) took 786 milliseconds (0.786 seconds) to run.
 8 bytes of memory allocated.
NIL
? (let ((foo (make-instance 'foo :x 1)))
    (declare (type foo foo))
    (without-interrupts
     (time (dotimes (i 1000000)
             (foo-x foo)))))
(DOTIMES (I 1000000) (FOO-X FOO)) took 286 milliseconds (0.286 seconds) to run.
Of that, 1 milliseconds (0.001 seconds) were spent in The Cooperative Multitasking Experience.
 16 bytes of memory allocated.
NIL
? (let ((foo (make-instance 'foo :x 1)))
    (declare (type foo foo)
             (optimize (speed 3) (safety 0)))
    (without-interrupts
     (time (dotimes (i 1000000)
             (foo-x foo)))))
(DOTIMES (I 1000000) (FOO-X FOO)) took 277 milliseconds (0.277 seconds) to run.
NIL
? (setq *super-optimize-primary-slot-access* t)
T
? (let ((foo (make-instance 'foo :x 1)))
    (declare (type foo foo)
             (optimize (speed 3) (safety 0)))
    (without-interrupts
     (time (dotimes (i 1000000)
             (foo-x foo)))))
(DOTIMES (I 1000000) (FOO-X FOO)) took 18 milliseconds (0.018 seconds) to run.
NIL
? (setq *super-optimize-primary-slot-access* nil)
NIL
? 


New table-dialog-item implementation - 4.1 & 3.2
================================================

The new table-dialog-item implementation is upwardly compatible with the
old one. To support tables with huge numbers of elements, MCL's
point code can now represent points that don't fit in 32 bits.
If either dimension is bigger than (signed-byte 16), the point is
represented as a cons. make-point, point-h, & point-v support this
representation. point-h & point-v are no longer inlined, though
The new functions integer-point-h & integer-point-v are.

New table-dialog-item initargs:

:rows, :columns
  You can use these instead of :table-dimensions to specify the
  dimensions of the table.

:separator-size :separator-visible-p :separator-color :separator-pattern
  These control the separators between rows and columns.
  :separator-size is a point specifying the size of the QuickDraw pen
    while drawing the separator.
    Default: #@(0 0) meaning no separator.
  :separator-visible-p is a boolen. If false, the separator is not drawn.
    Space is still left for it, however.
    Default: true.
  :separator-color is the color of the separator lines.
    Default: *gray-color*.
  :separator-pattern is the pen pattern while drawing the separator lines.
    If it is a macptr, that macptr IS the pattern. If it is a bound symbol,
    its symbol-value is the pattern. If it is a function, the result of calling
    that function with no arguments is the pattern.
    Default: '*black-pattern*.

New table-dialog-item accessors. All have SETF methods for changing their values:

separator-size, separator-visible, separator-color, separator-pattern
  These are used to get or set the information about the row and column
  separator lines.

table-row-height table row-number
table-column-width table column-number
  Used to customize the row height and column width of individual
  rows and columns.

There are three new internal generic functions:

draw-table-cell-new table h v rect selectedp
  Use this in new code instead of draw-table-cell to avoid the need
  to cons a point for the "cell" arg to draw-table-cell.
  draw-table-cell methods are still supported.

new-map-selected-cells table f
  Calls f with three arguments for each selected cell.
  The three arguments are: table, h, v.
  Use this in new code instead of map-selected-cells to
  avoid the need to cons a point for the second argument to
  the mapping function.

cell-contents-string-new table h &optional v
  Use this instead of cell-contents-string to avoid the need
  to cons a point for the "cell" argument.


Support for the :|styl| scrap - 4.1 & 3.2
=========================================

The :|styl| scrap is how Mac word processors record the style
information for a copied text selection. MCL now supports it.
Cut or Copy from a Fred window will store a :|styl| scrap
and paste into a Fred window will use the information found
in the :|styl| scrap. This feature can be disabled, making
all external text scraps style-less by setting the variable
ccl:*use-external-style-scrap* to NIL.

The :|styl| scrap represents colors with an RGBColor record.
Fred only supports 256 different colors. Hence any pasted
colored text is changed to the closest color that Fred
supports. This means that copying colored text from another
application, pasting it into MCL, then copying it from MCL
and pasting it back into the other application will change
the color to the closest entry in the default system 256-color
palette.

The :|styl| scrap also contains explicit ascent and line height
information for each font run. MCL ignores this information
on input and writes the default information for the font
on output.

Holding down the shift key while copying from or pasting to a fred
item toggles whether it copies or pastes with styles. This only
happens when the function in question is called during event
processing. If called outside of event processing, the shift key is
ignored.