[ Predicate Database and Compiler | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

mode +PredModes

Specifies the mode (calling pattern) for the given predicates.
+PredModes
Compound term whose arguments are +, ++, - or ? or a comma-separated list of such compound terms.

Description

The call of the predicate informs the compiler that the arguments of the specified predicate will always have the corresponding form when the predicate is called. The compiler takes this information into account when the predicate is compiled and generates more compact and/or faster code. Specifying the mode of a predicate that has been already compiled has no effect, unless it is recompiled. If the specified procedure does not exist, a local undefined procedure is created.

The possible argument modes are: 

+   The argument is instantiated, i.e.  it is not a variable.

++  The argument is ground.

-   The argument is not instantiated, it must be a free variable without
    any constraints, especially it must not occur in any other argument and
    it cannot be a suspending variable.

?   The mode is not known or it is neither of the above ones.
mode/1 is an operator and accepts also comma-separated list of mode specifications in the form 

   mode p(+), q(-), r(++, ?).
This operator binds less than comma, so the argument of mode/1 might have to be parenthesised when it is followed by other goals. Modes for built-in and external predicates are ignored. Modes are significant only for the first 15 arguments, for higher arguments the mode is always taken as ?.

NOTE: If the instantiation of the predicate call violates its mode declaration, no exception is raised and its behaviour is undefined.

Fail Conditions

None.

Resatisfiable

No.

Exceptions

(4) instantiation fault
PredModes is not instantiated
(5) type error
PredModes is not a compound term or a comma list or its arguments are not the above specified atoms.

Examples

Success:
    % code size:
    % no mode declarations
    [eclipse]: [append].
    /home/eclipse/src/append.pl compiled 212 bytes in 0.03 seconds

    % mode for one argument decreases the code size
    [eclipse]: mode(append(++, ?, ?)), [append].
    /home/eclipse/src/append.pl compiled 120 bytes in 0.00 seconds

    % modes for other arguments further decreases the size
    [eclipse]: mode(append(++, ++, -)), [append].
    /home/eclipse/src/append.pl compiled 92 bytes in 0.00 seconds

    % size of the trail stack
    cygnus% cat p.pl
    p(f(1), [output]) :- !.
    p(f(2), [another_one]).

    test :-
        p(f(1), X),
        statistics(trail_stack_used, T1),
        writeln(T1).
    :- test.
    cygnus% eclipse
    ECLiPSe Version 3.0 beta, 5/4/90 Copyright ECRC GmbH
    [eclipse]: [p].
    16
    /home/eclipse/p.pl    compiled 540 bytes in 0.02 seconds

    % With modes the code is shorter and does less trailing
    [eclipse]: mode(p(++, -)), [p].
    12
    /home/eclipse/p.pl    compiled 408 bytes in 0.02 seconds

    % bad mode declaration:
    [eclipse]: mode(p(+)), [user].
     p(a).
     user   compiled 40 bytes in 0.00 seconds

    yes.
    [eclipse]: p(X).    % call violates the mode declaration

    no (more) solution.
Error:
    mode p(X).                         (Error 4).
    mode p(+), get_flag(p/1, mode, X). (Error 5).
    % equivalent to mode((p(+), get_flag(p/1, mode, X)))

See Also

compile / 1, get_flag / 3, set_flag / 3