HELP DECLARE                                     John Williams, Apr 1988

This file explains how Poplog Common Lisp reacts to declarations made
with the special form declare, the macro declaim, and the function
proclaim.


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Standard Declaration Specifiers
  2   Non-Standard Declaration Specifiers
  3   Constant
  4   Declaration
  5   Dynamic-Extent
  6   Ftype
  8   Ignore
 10   Notinline
 11   Optimize
 12   Special
 13   Type


-----------------------------------------------------------------------
1  Standard Declaration Specifiers
-----------------------------------------------------------------------

Common Lisp provides the following standard declaration specifiers:

    declaration
    dynamic-extent
    ftype
    ignorable
    ignore
    inline
    notinline
    optimize
    special
    type


-----------------------------------------------------------------------
2  Non-Standard Declaration Specifiers
-----------------------------------------------------------------------

Poplog provides two further non-standard declaration specifiers:

    constant
    optimise

The meaning of constant is discussed below. optimise is provided as a
synonym for optimize, for the convenience of programmers used to British
spelling.

Note: constant and optimise are external symbols of the Poplog package.


-----------------------------------------------------------------------
3  Constant
-----------------------------------------------------------------------

The Poplog-specific declaration:

    (constant symbol value)

proclaims that symbol denotes the constant value. It is used in the
expansion of the macro defconstant. The value form is not evaluated.
This declaration can only be made globally, via proclaim.


-----------------------------------------------------------------------
4  Declaration
-----------------------------------------------------------------------

The declaration:

    (declaration {name}*)

proclaims its arguments to be valid declaration names. It is mainly used
to prevent the compiler from objecting to declarations meant for another
Common Lisp's compiler. This declaration can only be made globally, via
proclaim.


-----------------------------------------------------------------------
5  Dynamic-Extent
-----------------------------------------------------------------------

The declaration:

    (dynamic-extent {name}*)

declares that the data objects referred to by the given names (which may
be function or variable names) have `dynamic extent'.

Poplog uses this declaration only when name is that of the &rest
parameter of the immediately enclosing function definition. In this
case, the compiler arranges for the list of arguments that is bound to
the &rest parameter name at run-time to be returned to a free list when
the function exits.


-----------------------------------------------------------------------
6  Ftype
-----------------------------------------------------------------------

The declaration:

    (ftype (function ({argument-type}*) result-type)
           {function-name}*)

has one very important use in Poplog Common Lisp: it enables the
programmer to inform the compiler how many results a function produces.

The compiler will use this information to plant more efficient calls to
the function, provided that the name of the function has been declared
inline.

Once an ftype declaration for a function name has been made, subsequent
assignments to that function name will be typed-checked for consistency
with the original ftype declaration.

Note that the compiler is sometimes able to deduce the number of
results a function will produce by analysis of its code.


-----------------------------------------------------------------------
7  Ignorable
8  Ignore
-----------------------------------------------------------------------

These declarations are not acted upon by Poplog Common Lisp.


-----------------------------------------------------------------------
9  Inline
10  Notinline
-----------------------------------------------------------------------

The inline declaration informs the compiler that it is desirable to
open-code calls to certain functions. The notinline declaration has the
reverse effect. See HELP * INLINE for Poplog-specific details.


-----------------------------------------------------------------------
11  Optimize
-----------------------------------------------------------------------

The optimize declaration enables programmers to indicate the relative
importance of various performance characteristics to their application.
See HELP * OPTIMIZE for Poplog-specific details.


-----------------------------------------------------------------------
12  Special
-----------------------------------------------------------------------

The declaration:

    (special {variables}*)

specifies that the named variables are special (i.e. undergo dynamic
rather than lexical binding when used in a let form or as a lambda-list
parameter).


-----------------------------------------------------------------------
13  Type
-----------------------------------------------------------------------

The declaration

    (type type-spec {variables}*)

constitutes a guarantee by the programmer that the values of variables
will always be of the given type-spec.

Poplog only takes note of type declarations if type-spec is function (or
a sub-type such as compiled-function). In this case, the compiler plants
slightly more efficient code when the function-typed variable appears as
the first argument to apply or funcall.



--- C.all/lisp/help/declare
--- Copyright University of Sussex 1988. All rights reserved.
