chickadee » chicken » declarations

Declarations

Declarations can be used to control compiler settings directly inside the compiled code and are always global in scope. In many (but not all) cases an associated command-line option exists. When in conflict, declarations override command-line options. When multiple declarations conflict, the one appearing textually last overrides any previous one.

Declarations can be used to improve performance and to give entities like procedures and variables special properties that can result in better performing code. Most of these declarations subtly change the semantics of standard Scheme code with respect to the declared entities, so care must be taken when using them.

Declarations are always ignored in csi (the interpreter) or in evaluated code.

declare

(declare DECLSPEC ...)syntax

Process declaration specifiers. Declarations always override any command-line settings. Declarations are valid for the whole compilation-unit (source file), the position of the declaration in the source file can be arbitrary. Declarations are ignored in the interpreter but not in code evaluated at compile-time (by eval-when or in syntax extensions loaded via require-extension). DECLSPEC may be any of the following:

always-bound

[declaration specifier] (always-bound IDENTIFIER ...)

Declares that the given variables are always bound and accesses to those have not to be checked.

block

[declaration specifier] (block)

Assume global variables are never redefined. This is the same as specifying the -block option.

block-global

hide

[declaration specifier] (block-global IDENTIFIER ...)
[declaration specifier] (hide IDENTIFIER ...)

Declares that the toplevel bindings for IDENTIFIER ... should not be accessible from code in other compilation units or by eval. Access to toplevel bindings declared as block global is also more efficient. (declare (hide)) is equivalent to (declare (block)).

bound-to-procedure

[declaration specifier] (bound-to-procedure IDENTIFIER ...)

Declares that the given identifiers are always bound to procedure values.

enforce-argument-types

[declaration-specifier] (enforce-argument-types IDENTIFIER ...)

Declares that the toplevel procedures listed check the type of their arguments (either explicitly or by calling other enforcing procedures) and so a successfull invocation will indicate the arguments are of the types declared.

export

[declaration specifier] (export IDENTIFIER ...)

The opposite of hide. All given identifiers will be exported and all toplevel variables not listed will be hidden and not be accessible outside of this compilation unit.

emit-external-prototypes-first

[declaration specifier] (emit-external-prototypes-first)

Emit prototypes for callbacks defined with define-external before any other foreign declarations. Equivalent to giving the -emit-external-prototypes-first option to the compiler.

disable-interrupts

[declaration specifier] (disable-interrupts)

Disable timer-interrupts checks in the compiled program. Threads can not be preempted in main- or library-units that contain this declaration.

emit-import-library

[declaration specifier] (emit-import-library MODULENAME | (MODULENAME FILENAME) ...)

Declares that any following definition of a module named MODULENAME should be written to an external file (either a specified one or a file named "MODULENAME.import.scm"). The compiler option -emit-import-library may also be used instead.

Note that the import library is only generated if it cannot be found in the current directory, or if it exists but is not equal to the one that would be generated.

emit-types-file

[declaration specifier] (emit-types-file [FILENAME])

Enables generation of a types file for the current compilation unit, which will be written to the specified FILENAME or to <source-filename>.types in the current directory. This filename can be overridden with the -emit-types-file command line flag, which takes precedence over this declaration.

inline

[declaration specifier] (inline)
[declaration specifier] (not inline)
[declaration specifier] (inline IDENTIFIER ...)
[declaration specifier] (not inline IDENTIFIER ...)

If given without an identifier-list, inlining of known procedures is enabled (this is equivalent to the -inline compiler option). When an identifier-list is given, then inlining is enabled only for the specified global procedures. The negated forms (not inline) and (not inline IDENTIFIER) disable global inlining, or inlining for the given global procedures only, respectively.

inline-global

 [declaration specifier] (inline-global)
 [declaration specifier] (not inline-global)
 [declaration specifier] (inline-global IDENTIFIER ...)
 [declaration specifier] (not inline-global IDENTIFIER ...)

Declare that then given toplevel procedures (or all) are subject to cross-module inlining. Potentially inlinable procedures in the current compilation unit will be written to an external <source-filename>.inline file in the current directory. Globally inlinable procedures from other compilation units referred to via (declare (uses ...)) or require-extension are loaded from .inline files (if available in the current include path) and inlined in the current compilation unit.

Enabling global inlining implies (declare (inline)).

inline-limit

[declaration specifier] (inline-limit THRESHOLD)

Sets the maximum size of procedures which may potentially be inlined. The default threshold is 20.

unroll-limit

[declaration specifier] (unroll-limit LIMIT)

Sets the maximum number of times a self-recursive call is inlined and so effectively "unrolled". The default limit is 1.

keep-shadowed-macros

[declaration specifier] (keep-shadowed-macros)

Normally, when a toplevel variable is assigned or defined that has the same name as a macro, the macro-definition will be removed (in addition to showing a warning). This declaration will disable the removal of the macro.

local

[declaration specifier] (local)
[declaration specifier] (local IDENTIFIER ...)

Declares that the listed (or all) toplevel variables defined in the current compilation unit are not modified from code outside of this compilation unit. See also the documentation for the -local compiler option about the implications of this.

no-argc-checks

[declaration specifier] (no-argc-checks)

Disables argument count checking.

no-bound-checks

[declaration specifier] (no-bound-checks)

Disables the bound-checking of toplevel bindings.

no-procedure-checks

[declaration specifier] (no-procedure-checks)

Disables checking of values in operator position for being of procedure type.

no-procedure-checks-for-usual-bindings

[declaration specifier] (no-procedure-checks-for-usual-bindings)

Disables checking of procedures for the default standard- and extended toplevel bindings.

no-procedure-checks-for-toplevel-bindings

[declaration specifier] (no-procedure-checks-for-toplevel-bindings)

Disables checking of procedures for calls to procedures referenced via a toplevel variable (calls to explicitly named procedures).

predicate

[declaration specifier] (predicate (IDENTIFIER TYPE) ...)

Marks the global procedure IDENTIFIER as a predicate on TYPE.

profile

[declaration specifier] (profile IDENTIFIER ...)

Enable profiling exclusively for given identifiers. Normally the compiler enables profiling decorations for all globally defined procedures. With this declaration, profiling can be enabled for selected procedures.

pure

[declaration specifier] (pure IDENTIFIER ...)

Declares the procedures with the names IDENTIFIER ... as referentially transparent, that is, as not having any side effects. This can help the compiler to remove non-side-effecting expressions.

number-type

fixnum-arithmetic

[declaration specifier] ([number-type] TYPE)
[declaration specifier] (fixnum-arithmetic)

Declares that only numbers of the given type are used. TYPE may be fixnum or generic (which is the default).

compile-syntax

[declaration specifier] (compile-syntax)

Equivalent to the compiler option of the same name - macros defined in the compiled code are also made available at runtime.

safe-globals

[declaration specifier] (safe-globals)

Assumes variables assigned in the current compilation unit are always bound and that any calls to these variables can always be assumed to be calls to proper procedures.

specialize

[declaration specifier] (specialize)

Enables specialization. This is equivalent to passing the -specialize option to the compiler.

standard-bindings

[declaration specifier] (standard-bindings IDENTIFIER ...)
[declaration specifier] (not standard-bindings IDENTIFIER ...)

Declares that all given standard procedures (or all if no symbols are specified) are never globally redefined. If not is specified, then all but the given standard bindings are assumed to be never redefined.

strict-types

[declaration specifier] (strict-types)

Declares that the type of variables is not changed by assignment. Equivalent to giving the -strict-types compiler option.

type

 [declaration specifier] (type (IDENTIFIER TYPE) ...)

Declares toplevel procedures to have a specific type for scrutiny. IDENTIFIER should name a toplevel variable and TYPE should be a type specification. A type-declaration overrides any previous declaration for the same identifier. See also Types for more information about using types, the syntax of type-specifiers and a more convenient type-declaration syntax (:).

extended-bindings

[declaration specifier] (extended-bindings IDENTIFIER ...)
[declaration specifier] (not extended-bindings IDENTIFIER ...)

Declares that all given non-standard and CHICKEN-specific procedures (or all if no symbols are specified) are never globally redefined. If not is specified, then all but the given extended bindings are assumed to be never redefined.

usual-integrations

[declaration specifier] (usual-integrations IDENTIFIER ...)
[declaration specifier] (not usual-integrations IDENTIFIER ...)

Declares that all given standard and extended bindings (or all if no symbols are specified) are never globally redefined. If not is specified, then all but the given standard and extended bindings are assumed to be never redefined. Note that this is the default behaviour, unless the -no-usual-integrations option has been given.

unit

[declaration specifier] (unit IDENTIFIER)

Specify compilation unit-name (if this is a library)

unsafe

[declaration specifier] (unsafe)
[declaration specifier] (not safe)

Do not generate safety-checks. This is the same as specifying the -unsafe option. Also implies

(declare (no-bound-checks) (no-procedure-checks) (no-argc-checks))

unused

[declaration specifier] (unused IDENTIFIER ...)

Disables any warnings when the global variable IDENTIFIER is not defined but used, or defined but never used and not exported.

uses

[declaration specifier] (uses IDENTIFIER ...)

Gives a list of used library-units. Before the toplevel-expressions of the main-module are executed, all used units evaluate their toplevel-expressions in the order in which they appear in this declaration. If a library unit A uses another unit B, then B's toplevel expressions are evaluated before A's. Furthermore, the used symbols are registered as features during compile-time, so cond-expand knows about them.

Previous: Types

Next: Extensions