%MAN OFF%
\section{User annotations: telling \cmix{} what it can't figure out itself}
\label{user-ann}

The core of the \cmix{} system is a set of automatic analyses that decide which
of the actions and values in the subject program should be spectime and which
should be residual. Most of the time the analyses do a good job, but they
don't perform micracles, nor do they read minds.

\emph{User annotations} are
about telling \cmix{} that you know better than it which binding time a
value or
an action should have. Few programs need no user annotations, most programs
need a few, and some programs need a lot of them to specialize satisfactorily.
This section describes the types of user annotations you can attach to your
program and how to do it.

Whether user annotations should be placed in the
subject program itself or in a separate file is a matter of style.
\cmix{} supports both choices by expressing
(most) user annotations as specializer directives
which can appear either in the subject program or in a script file.

\subsection{Sorts of user annotations for variables}
\label{user-ann-vars}

\iffalse
%MAN ON
%MAN%.SH USER ANNOTATIONS
User annotations are specializer directives that affect the
binding times of the values and actions in the program. There is
one set of user annotations for variables and another set of
annotations for calls to external functions. An external function
can itself be annotated, which applies to all calls of it that have
no explicit annotation.
%MAN%.SS User annotations for variables
%MAN OFF
\fi

You can attach these annotations to variables in the subject
program:
%MAN ON
\begin{description}

\item[»spectime«] --
Use this for variables that you want to exist only at
spectime. This doesn't actually change the binding-time analyses, but if
\cmix{}
finds any reason to want the variable to be residual, it will not produce a
generator but instead give an error message and terminate.
%MAN OFF

It can be helpful
to place this annotation on some of the variables you hope to specialize away.
You will then get immediate response if this is not possible, and
the error message might be more helpful in pointing out the problem than the
machine-annotated program.

%MAN ON
This annotation can not be used for variables that have only »extern«
declarations in the \cmix{} input files.
%MAN OFF
Such variables are always
forced to be residual.
(But see the »dangerous«~»spectime« annotation below).

%MAN ON
\item[»dangerous spectime«] --
Prevents an external variable with no definition from being residualized.
This can sometimes help making the specialization
process use less
resources, but also has a real potential for making the residual program
incorrect, because \cmix{} cannot track changes to the value of the
variable without having control over its definition.
%MAN OFF
\emph{This severely compromises \cmix's
ability to produce correct residual programs! Do think the case over at least
twice before using this annotation.}

You can safely ignore this annotation until you
are sure that you need to do something radical about the efficiency of the
generating extension.

%MAN ON
\item[»residual«] --
Use this to tell \cmix{} to assign binding-times so that the
variable becomes
completely residual. This normally forces other variables and values to be
residual as well; that happens automatically and you need not provide user
annotations for those.
%MAN OFF
(Also, it might make it impossible to
fulfil another »spectime« annotation).

This annotation is the primary
tool for
controlling a specialization that would otherwise proceed infinitely or
produce unacceptably large residual programs. Examples of the use of
»residual« are given in the \cmix{} tutorial.

%MAN ON
\item[»visible spectime«] --
This has the same effects as »spectime« and additionally specifies that
the variable should have external linkage in the generating extension.
Namely, the variable will be ``visible'' to other program modules.
%MAN OFF

This annotation should be used for variables that you want to be shared
between the generating extension and code that you
(unbeknownst to \cmix) link together with it. It might either be variables
that are initialized by a user-supplied »main« function before the generator
functions are called, or variables that are used by external functions
annotated as »spectime«.

%MAN ON
\item[»visible residual«] --
This has the same effects as »residual« and additionally specifies that
the variable should have external linkage in the residual program.
%MAN OFF

This annotation is useful for variables that should shared among
the residual program
and program parts that have not been partially evaluated.

%MAN ON
\end{description}

\manIgnore{\noindent}
The two »visible~...« annotations can only be applied to variables that
have
\begin{itemize}
\item external linkage, \emph{and}
\item a definition (\ie a file-level declaration without »extern«, but
possibly with an initializer)
\end{itemize}
in the original program. These are the only variables where visibility is a
question at all.
%MAN OFF
If you wonder why one would want one of these variables to
\emph{not} have external linkage in \eg the residual program, remember that
\cmix{} can specialize several source files together to one, and that the
variable
might be used only by those files. This is actually what \cmix{} assumes if you
do not tell it otherwise---even if there is only one file: many C programmers
are lazy and define their global variables as »int«~»frob;« where
»static«~»int«~»frob;« would have been more appropriate.

Note that the order of the words matter: there is no annotation called
»residual«~»visible«. The two concepts of ``residual'' and ``visible''
are not independent; it would be pointless to just declare a variable
»visible« but leave it to \cmix{} to decide if it should be visible in
the generating extension or the residual program!
%MAN ON

Objects with external linkage but without a definition are always ``visible'';
if you do not annotate them with »dangerous«~»spectime«, \cmix{} will default
to »residual«.
All other variables without user annotations will have a binding time
selected by \cmix{} and will be internal to the generated source files.

%MAN OFF
\iffalse
One planned extension to \cmix{} is the ability to select different binding
times to a local variable that has multiple uses in the function.
It will not be possible to control this by user annotations. If you want to
force a binding time upon only certain uses of a local variable we suggest
declaring a new variable for these uses and annotate that instead.
\fi

\subsection{How to write user annotations for variables}
%MAN ON
%MAN-TEX:You apply a user annotation to a variable by writing
\manIgnore{Write} a specializer directive reading \eg
\example{visible spectime: variable\_name}

For global variables---whether their linkage is internal or external---simply
name them in the specializer directive. Local variables (including »static«
ones) and function parameters use the two-part syntax (think C++)
\example{«annotation-name»: «function»::«localname»}
%MAN OFF

Thus,
\example{\#pragma cmix residual: foo zugol::br}
in a C source file forces the global »foo« and the local or parameter
»br« in function »zugol()« to be residual.

If you try to annotate a global which exists (with internal
linkage) in several different files, or a local variable whose name is
not unique within the function (because it is defined in several blocks
inside it) you will have a warning thrown at you and every matching variable
gets annotated. Please contact us if this is a real problem for you.

\subsection{Sorts of user annotations for functions}

The specialization of functions defined in the subject
program (\ie functions whose body is seen by \cmix) can be controlled
by adding annotations to their formal parameters or local variables.
These functions (even those that have external linkage
in the source files)
are never ``visible'' outside either the generating extension or the residual
program. (If you think you need to make a function visible
in the generating extension, the »generator:« specializer directive described
in \ref{generator directive} is probably what you are really looking for).


However, when you call a function whose definition \cmix{} cannot see,
\cmix{} has no way of deducing whether the call should be made at spectime or
in the residual program, or what types of side effects may result from
the call. A number of annotations are available to control how
external calls are handled. They fall in two groups. The first group
control which assumptions \cmix{} makes about possible side effects
through the function calls. The second group provides control of when
the function call is actually made.

%MAN%.SS User annotations about side-effects from external functions:
%MAN ON
\begin{description}

\item[»pure«] --
The external function does not commit any side effects at all. Its
return value does not depend on anything but the argument values (and,
if one of the arguments is a pointer, the data that pointer point to,
and so on recursively).

%MAN OFF
Typical functions that fit this description are »sin()« and other
mathematical functions%
\footnote{\cmix{} will automatically insert »pure« annotations for
the functions in »math.h« when you include the header file. Actually some of
these functions sometimes have the side effect of setting »errno«, \eg when
one tries to execute »sqrt(-1.0)«. However, we haven't yet figured out how to
make \cmix{} take this into consideration and still reach a speed benefit.
Since nobody ever seems to actually check »errno« after calling one of these
functions, we are quietly going to ignore this matter henceforth.}%
.
%MAN ON

\item[»stateless«] --
The external function may commit some side effects, but they only
depend on the argument values (and the objects pointed to by the
argument values, and so on). In particular, the only objects that
may have their values changed by the call are those pointed to
(perhaps indirectly) by the argument---the function does not
have any internal ``state''.

\item[»rostate«] --
The external function may still not change any objects not
reachable from the arguments, but the values that are written
into them and returned from the function may depend on some
kind of external state.

\item[»rwstate«] --
The function can be expected to do anyting a C function may legally
do, including changing the values of any objects that it knows the
address of, and including changing an external state which affects
later calls to »rostate« or »rwstate« functions.

This is assumed as the default by \cmix when no explicit annotation
is given.

\cmix only allows »rwstate« calls to happen at spectime if it can
prove that they will be performed in precisely the same sequence
as if the source program was run unspecialized.
%MAN OFF
Evidently, if the sequence and
number of »spectime« calls depend on the program's dynamic input (or if
\cmix{} just isn't smart enough to realize they don't)
%MAN%If
%MAN ON
this is impossible, and
an error message will result.

%MAN-TEX: \end{description}
%MAN%.SS User annotations about when external functions are called
%MAN-TEX: \begin{desctiption}

\item[»spectime«] --
This annotation specifies that all calls of the function
should happen at spectime. If \cmix{} cannot make sure that all parameters in
a call are known at spectime, it aborts with an error message which
(hopefully) helps you understand why it is so.

This annotation is intended to be placed on \eg functions that read in parts
of the spectime input that are not given as arguments to the goal function.

\item[»residual«] --
This annotation specifies that the function may only be called in the residual
program.

\item[»anytime«] --
This annotation is the default and
specifies that the function may be called either
at spectime
or at residual time, depending on how soon all of the arguments are available.

However, if the function is also annotated »rwstate« or »rostate«, it
will only be called at spectime if that is explicitly requested. (That
is, for such function »anytime« is really equivalent to »residual«).

\end{description}
%MAN OFF
\iffalse
%MAN ON

You annotate a call to an external function by writing the annotation
name as a parameter to the predefined »\_\_CMIX« macro before the
function name, such as
\example{\_\_CMIX(rostate spectime)printf(""spectime output"");}
You can give a state-annotation or a calling-time annotation or (as in
the example) both.
A default setting for all calls to a given external function can be specified
by writing a specializer directive of the form
\example{«annotation-name»: «fun»()}
%MAN OFF
\fi

\subsection{How to write user annotations for functions}

This is even simpler than for variables:
\example{stateless spectime: gizmo() gadget()}
You don't need the »::« syntax, or worry about name clashes, since function
annotations are only concerned with symbols with external linkage.

In a single annotation you can give either one of
»pure«, »stateless«, »rostate«, or
»rwstate«, or one of »spectime«, »anytime«, or »residual«, or one
annotation from each group.

\smallskip

But this is not the whole story: you can also annotate an individual function
call, thereby overriding the (perhaps default) annotation on the function
\textit{per se}.  This can't be done as a specialization directive, primarily
because the developers coundn't think of a good way to specify precisely which
call the annotation is aimed at.

Overriding of single function calls is meant primarily for basic I/O functions
such as »fopen()«, »fgets()«, etc. that are used to read spectime as well as
residual input in the same program. Those calls that read the spectime input
can be annotated »spectime«, leaving the reads of residual inputs residual.

You annotate a single function call by prefixing it with
»\_\_CMIX(««annotation name»»)« right in the code. That is, to
annotate the call to »gor()« in
\example{z = bul() + gor(42);}
as »spectime«, you would write
\example{z = bul() + \_\_CMIX(spectime)gor(42);}

If you use this syntax you'll probably also want to insert something like
\begin{verbatim}
       #ifndef __CMIX
       #  define __CMIX(garbage) /*nothing*/
       #endif
\end{verbatim}
at the top of the affected files, so your progam will also compile without
C-Mix. Or maybe even (though it might interfere with our ability to write
specializer directives as »\#pragma«s on systems where such lines are subject
to macro replacement):
\begin{verbatim}
       #ifdef __CMIX
       #  define spectime __CMIX(spectime)
       #else
       #  define spectime /*nothing*/
       #endif
       /* blah blah */
       z = bul() + spectime gor(42);
\end{verbatim}

\subsection{Commentary on the »dangerous spectime« annotation}
\label{dangerous spectime}
The problem with »dangerous spectime« is that \cmix{} cannot take the
value of a such-annotated variable into account when it considers
whether an already
generated piece of residual code can be reused in a given situation. Consider
this code:
\begin{verbatim}
       extern int ex ;
       int in ;
       #pragma cmix spectime: in ; dangerous spectime: ex ;
       void showthem() {
           __CMIX(spectime) printf("ex=%d, in=%d\n",ex,in);
       }
       #pragma cmix generator: main specializes goal()
       void goal() {
           ex = 117 ; in = 1001 ;
           showthem();
           in = 42 ;
           showthem();
           ex = 1984 ;
           showthem();
       }
\end{verbatim}
This program causes only \emph{two} residual versions of »showthem()« to
be generated: one for $»in«=1001$ and one for $»in«=42$, and each one
will have embedded the value »ex« has when it is first discovered that the
function is needed. This happens to be 117, so the residual program will
(errorneously) output,
\begin{verbatim}
       ex=117, in=1001
       ex=117, in=42
       ex=117, in=42
\end{verbatim}
And worse yet: \cmix{} does not detect that there is any problem at all.

It follows that one has to be extremely careful when using this annotation.
It is always safer and nearly always better to move
the definition of the variable into \cmix's view (possibly by moving it to a
source file of its own) and use »visible«~»spectime«.

The reason the annotation exists at all is that in a few cases the deficiency
can be turned into a advantage. If the variable is \eg a large array and you are
really absolutely sure that \cmix{} doesn't need to keep track of changes to
it (ideally because there aren't any), then this annotation may cause
the generating extension to use significantly less time and space. This is
because then it doesn't need to remember the variable's previous contents and
compare it every time code is to be shared.

