\section{Introducing \cmix}
\label{intro}

Those of us who have been in the game long enough to have started programming
in interpreted BASIC on a machine with an astronomical 48KB of RAM remember
the shocking relevation that for Real Programming Languages
running your program was
a two-step process: one had to \emph{compile} one's program before it
could run. What an amazingly bizarre arrangement! We quickly learned, however,
that the clumsiness paid well: compiled programs are much faster than
equivalent interpreted programs, typically by an order of magnitude or more%
\footnote{The reader will allow us a little rethorical latitude with respect
to the historical facts. The author \emph{is} aware that BASIC might
not be an ideal programming language but by any sensible definition
certainly is a \emph{real} language; that compilers for BASIC do and
did exist; that compilers were used before interpreters were, and so on.}.

\figurehere{intro-ic}{Interpreting versus compiling}

\emph{Partial evaluation} does something similar to the process of running a
program: what used to be a single process is split into two. Somewhat
analogous to the compiler, we introduce a utility called a
\emph{specializer} (or, as it is
also called: a \emph{partial evaluator}) that transforms the program before we
run it.

\figurehere{intro-cpe}{Compiling versus partial evaluation}

The objective is the same as when compiling: the transformed program often
runs much faster than when we run it directly%
\footnote{The increase in speed is not always as big as the orders of
magnitude yielded by compiling, though in some cases it can be.}.
But the method is different: The compiler speeds up the program by
expressing it in a language closer to the hardware of the machine.
The specializer needs to be
told some of the program's input, and uses that knowledge to reduce the
program's workload. This is illustrated in figure \ref{intro-cpe}.

The similarities between compiling and partial evaluation are mentioned in
an attempt to ease understanding, not to suggest the specializer as a
replacement for the compiler. With \cmix{} you still compile your program, but
you do it after having improved the source code by partial evaluation.

\subsection{A simple example}

The easiest way to describe what partial evaluation does is probably by a
concrete example: Consider the program «xdup.c», alluded to in figures
\ref{intro-ic} and \ref{intro-cpe}. For the moment the
presentation will be easier to follow if we assume the ``program'' is only
a single function whose input »123« and »abc« come in two separate string
parameters 
(later we'll get back to the general case where «xdup» reads its
input from \eg »stdin«).
 Then the source «xdup.c» might look thus:
\label{xdup.c with parameters}
\begin{verbatim}
       #include <stdio.h>
       void xdupfun(char counts[], char data[]) {
           int i, t ; 
           for( i=0; counts[i]; i++ ) {
                t = counts[i]-'0' ;
                while( t-- )
                    putchar(data[i]) ;
           }
       }
\end{verbatim}

The specializer, presented with this \emph{subject program}, and the
information that »counts« is »123«, sees that the values of the local
variables »i« and »t« never depends on the values in the »data« parameter.
Thus all of the »i« and »t« manipulation can be done as soon as ``»123«'' is
available---that is, during the specialization process: we say that it is done
\emph{at spectime}\footnote{``Spectime'', of course, is a contraction of
``specialization time''. We use the shorter version because the concept
occurs
so frequently with \cmix{} that it was impractical to only
have a 6-syllable word
for it.}. Conversely the indexing of the »data« array cannot happen until the
array is there.

The specializer produces%
\footnote{This example is copied verbatim from actual output from
\cmix, except that we removed some blank lines.}
a file «xdup-123.c» looking like
\label{xdup-123.c with parameters}
\begin{verbatim}
       /* This program was generated by C-Mix/II
        *
        * THIS IS AUTOMATICALLY GENERATED CODE
        */
       #include <stdio.h>
       void
       xdupfun(char *residual_arg)
       {
         char *data;
         data = residual_arg;
         putchar((int )data[0]);
         putchar((int )data[1]);
         putchar((int )data[1]);
         putchar((int )data[2]);
         putchar((int )data[2]);
         putchar((int )data[2]);
         return ;
       }
\end{verbatim}
It is reasonable to expect this \emph{residual program} (called so because it
is what is left when the specializer has removed everything it can get away
with) to run faster than the original «xdup», because it does not have to
spend time with parsing the »counts« parameter.

If you had a program that called
\example{xdupfun("123",something);}
thousands of times, the time needed to specialize «xdup.c» might
pay back well in reduced execution times.

\subsection{Some advantages of partial evaluation}

``This is all very well,'' the sceptical reader may object here, ``but might
I not just as well have written «xdup-123.c» manually?'' The answer is that
yes, in some cases you might. But there are also reasons why you might
benefit from the partial evaluation approach:
\begin{itemize}
\item
You can easily change your mind about what you need. If you later find out
that what you really want is not «xdup-123.c» but a «xdup-456.c» or
«xdup-117.c», you would be faced with the task of developing a new function
from scratch. With \cmix{} that would be as easy as rerunning an automatic
utility with some revised parameters. You will save coding time as well
as debugging time: even if you do not trust \cmix{} so
much as to completely skip testing the automatically generated «xdup-456.c»,
\cmix{} certainly makes fewer trivial typos and spelling errors than a
human programmer.
\item
You may have «xdup.c» at hand already---perhaps because you're trying to speed
up an existing program, or the code may just be lying around from an early
prototype of the program you're developing. Your advantage is the same as when
you change your mind.
\item
It may actually be easier to develop «xdup.c» and specialize it than to
develop «xdup-123.c». This is hardly so in the example---because it
was deliberately chosen simple enough that the residual program is easy to
understand---but that is not an universal truth; a residual program can easily
have a more complex structure than the original subject program.
\end{itemize}

It might actually be worthwhile to think of the partial evaluator not as a
tool for speeding up programs but as a tool that lets you develop efficient
customized programs («xdup-123» etc.) with little more development and
maintenance effort than that of a single, general version («xdup»).
Analogously, a compiler can be viewed as either a program that speeds
up other programs, or as a utility that saves you the time it would take
to write your programs directly in assembler language for each machine
type they have to
run on.

\subsection{How to run \cmix{} on the example}

\figurehere{intro-cplx}{Neither compiling nor specialization are really as
simple as they seem in figure \ref{intro-cpe}.}

Now we describe what exactly must be typed to specialize the «xdup.c» shown on
page \pageref{xdup.c with parameters} with \cmix. It is a little more involved
than it seems in figure \ref{intro-cpe}, because the specialization which
appears as a ``black box'' on figure \ref{intro-cpe} actually involves
several steps when using \cmix. It will later become apparent that this makes
\cmix{} much more flexible, just as enhancing a compiler with a
separate linker step makes \emph{that} more flexible.

Figure \ref{intro-cplx} is closer to the full truth about \cmix{} than figure
\ref{intro-cpe} but a little more complex than we dared present to an
unprepared reader.

Now, assume that you have \cmix{} installed on your system and you have typed
in «xdup.c» in a working directory. Now, give the command%
%\footnote{The command line examples assume a Unix-like system with a csh-like
%shell. There may be small differences on other systems.}
\example{cmix xdup.c -e 'goal: xdupfun(\$1,?)'}
Let us have a closer look at that:
\begin{description}
\item[»cmix«]
is the name of \cmix's main program.
\item[»xdup.c«]
is the C source file that contains the subject program.
\item[»-e«]
specifies that the next argument is a \emph{specializer directive}.
Specializer directives supply \cmix{} with information that does not
directly follow from the subject program alone. Section \ref{directives} of
this manual describes all of the possibilities; here we just use one.
\item[»goal«]
is a keyword for this kind of specializer directive.
\item[»xdupfun«]
is the name of the function that we want to specialize. The input to
\cmix{} may include several functions, so it needs to be told which is the
one of which we want to produce a specialized form.
\item[»\$1«]
specifies that the first argument to »xdupfun« will be given at spectime. Note
that we do not yet specify what it is; its value will be given later, as the
first (hence the »1« in »\$1«) argument to the generating extension.
\item[»?«]
specifies that the second argument to »xdupfun« will not be known at spectime.
\end{description}

If everything goes well, \cmix{} will output two files: the generating
extension «xdup-gen.c», and an \emph{annotated subject program} in
the file «xdup.ann».

The annotated subject program is an encoded version of the C input with
annotations that aim at showing what will happen to the program as it
gets specialized. The file is not human-readable; you need to use the
»cmixshow« to read it. Give the command
\example{cmixshow xdup.ann}
and you will be shown a pretty-printed version of your program.

Some parts of the program will be shown in boldface by »cmixshow«.
Those are the parts of the program that have been
annotated \emph{residual}, meaning that they are not executed at
spectime but instead appear in the residual program.

Having verified that the annotated program looks okay, the next step is to
compile the generating extension. This is straightforward:
\example{cc xdup-gen.c -o xdup-gen -lcmix}

The »-lcmix«
links in a \cmix{} support library for generating extensions. You might need
to use additional options for the compiler to locate this library.

Compiling «xdup-gen.c» should produce an executable called «xdup-gen». Now is
the time to present the actual spectime input. Run «xdup-gen»:
\example{./xdup-gen 123}
and it outputs a residual program that is essentially equivalent to the one
shown on page \pageref{xdup-123.c with parameters} though the lay-out may be a
little different. If you had needed the residual program as more than an
example, you'd probably have redirected the output of «xdup-gen» to a file,
e.g. «xdup-123.c».

\medskip

The whole process may seem somewhat complicated, but most of it is easily
automated. The rest of this manual describes ways to control and customize the
individual steps.

\subsection{Advanced uses of »cmixshow«}
»cmixshow« can do much more than just tell you which parts of the
subject program have been annotated residual. It can also show you
\emph{why} it is so.

To use the advanced features of »cmixshow« you have to give the
option »-s« on the command line to »cmix« (note: »cmix« gets the »-s«
switch, not »cmixshow«). The most prominent effect of »-s« is that
the annotated program as shown by »cmixshow« gets transformed into
spaghetti code with lots of gotos and no structured control
statements. This form is closer \cmix{}'s internal representation
of the program; it is needed in order to be able to express the more
subtle facts about why things become residual.

The true power of »cmixshow« is unleashed if you define the
environment variable »BROWSER« to the name of you favorite
frames-capable WWW browser before you start »cmixshow«. Then
»cmixshow« will spawn a web browser to show you the annotated
program, with most of the identifiers hyperlinked to their
definitions.

Now you can enable hyperlinks from the program text to
explanations produced by \cmix{}'s analyses.
At the top of the program a button labeled ``Select visible
annotations'' button. Click it to get to
select which class of annotations you want
displayed. The different annotations are organised in a tree-like
structure; you can collapse and expand branches to your liking.
Initially no annotations are displayed; a common choice is to
expand the ``BTA'' branch and then turn off the ``Spectime''
annotations.

After clicking on the ``Ok, show me those!'' button, you'll again see 
your program, but with the residual parts decorated with hyperlinks
that lead to additional information about why they became dymanic
(shown in the lower frame of the browser).

The other annotation classes document the results of auxiliary
analyses. They are mainly useful when debugging \cmix{}, but can
also sometimes be useful to the end-user. Experiment with showing
them to see if you can make sense of the information. (If you can,
consider contributing a section to this manual!)
