%MAN OFF
\section{Writing abstract header files}
\label{shadow headers}
\def\manIgnore#1{#1}

Using abstract interfaces is a well-known technique in software
development. In C it is typically employed by definig the abstract
interface in a heder file. It is not uncommon that the header file
needs, for the benefit of the compiler, to include details
about the implementation of the interface. One example is the »FILE«
type defined by »stdio.h« or the constants defined in »limits.h«.

One use for a partial evaluator such as \cmix{} is to specialize
the code that uses the abstract interface with respect to the
implementation of it. In some cases this can lead to considerable
speedup, because partial evaluation can eliminitate the run-time
negotiation between the user code and the (otherwise separately
compiled) implementation. Specializing abstract interfaces away
in this fasion is not a problem with \cmix{}. You just let \cmix{}
read the user source and the implementation source files; \cmix{}
automatically invokes a C preprocessor that interpolates the contents
of the header files, and voila---the code gets specialized with
respect the implementation details.

However, it happens just as well that this is precisely \emph{not}
what you wants. That can have several reasons:
\begin{itemize}
\item You might want to be able to change the implementation of the
abstract code without changing the residual program. That means that
the residual program must honor the same abstraction as the original
source.
\item You may not have access to the source code for the
implementation of the abstract interface, only the partial information
that have to go in the headers. That may not be enough to gain any
useful specialization in itself so, \eg, the expansion of preprocessor
macros may have as its only effects putting a bigger load on the \cmix{}
system and making the annotated program produced by the analyzer
harder to read.
\item The implementation may depend on non-standard syntactic
extensions of the C compiler. Thus \cmix{} may not be able to read
the input at all if the header files are interpolated normally.
\end{itemize}

The solution in this case is to create an \emph{abstract header file}
that is included instead of the real header file when the source is
processed by \cmix{}. This is the technique we use to support standard
headers such as »stdio.h«. This section describes the constructions
\cmix{} supports for introducing abstraction into its conception
of the C language.

\subsection{The abstract header file itself}
There are two basic techniques for introducing abstractions.
\begin{itemize}
\item[1.] Use conditional compilation directives to make the
  same header file come out differently when read by \cmix{}
  or the C compiler. The header file might look something like
\begin{verbatim}
#ifndef MYHEADER_INCLUDED
  #define MYHEADER_INCLUDED
  #ifdef __CMIX
     /* define abstract interface here */
  #else
     /* define concrete interface here */
  #endif
#endif
\end{verbatim}
  This technique requires you to change the original source but
  may be the only option if the header file resides in the same directory
  as the ».c« files.
\item[2.] Write the abstract definition in a separate file with the
  same name as the original header file, and put it in a special
  directory. Use the »-I« option to make \cmix{} search special
  directory. This is often the cleanest solution and the one \cmix{}
  itself uses for the standard headers ( n which case the right »-I«
  is implied).
\end{itemize}

\noindent An abstract header definition generally consists of
\begin{itemize}
\item Administrative specializer directives to make the residual
  code and the generating extension interface properly to the
  concrete definition of the interface at compile time. The
  »header«, »well-known« and »taboo« directives described below
  are used for this.
\item Magic constant declarations with the »well-known constant«
  directive, discussed in section \ref{well-known constant}.
\item Abstract type declarations. There is a special syntax for
  these, to be discussed in section \ref{abstract}.
\item Normal declarations for function prototypes (possibly
  including ``functions'' which in the real header files are
  really function-like preprocessor macros) and/or external
  variables.
\item User annotations for those function and variables (see section
  \ref{user-ann}).
\end{itemize}

Many of these tasks are done with specializer directives. The
»\#pragma cmix« syntax for introducing specializer directives
from C source code was motivated partly from the need to include
specializer directives in abstract headers.

\subsection{Support directives for abstract headers}

\iffalse
%MAN ON
%MAN%.SH DIRECTIVES FOR ABSTRACT HEADERS
These specializer directives are used to implement
\emph{abstract headers}; see the full User Manual for a more
elaborate discussion of their use.
\begin{itemize}
%MAN OFF
\fi

\subsubsection{The »header:« directive}
\label{header directive}
%
%
\example{header: "myheader.h"}
%MAN ON
%MAN-TEX:\item[»header:« «word»]
This directive causes a
\manIgnore{\example{\#include "myheader.h"}}
%MAN-TEX:\example{\#include «word»}
line to be emitted to the beginning of the generating extension source
and the residual program source.
%MAN OFF
\cmix{} does not try to read »myheader.h«
and does not even check that it is a valid filename.

\subsubsection{The »well-known:« directive}
\label{wellknown directive}
%
%
\example{well-known: thisfun thatvar}
%MAN ON
%MAN-TEX:\item[»well-known:« «identifier»...]
This directive prevents \cmix{} from
emitting declarations for external variables or functions
named \manIgnore{»thisfun« or »thatvar«}
%MAN-TEX: with the given «identifier»s
when it emits the generating extension
and the residual program source. The
rest of the code is still generated as though a declaration was
present, so you'll have to make sure by some other means you won't
run into trouble with undeclared identifiers.

Note that function names do \emph{not} take a »()« here as the do
in user annotation directives.
%MAN OFF

The intended use is for external functions that get defined in
headers included with »header:« directives. The ``function'' may
actually be defined as a macro or have a slightly different
prototype in the header than \cmix{} thinks it should have. By
instructing \cmix{} to omit a declaration of its own, you can
avoid confusing the compiler.

\subsubsection{The »taboo:« directive}
\label{taboo directive}
%
%
\example{taboo: FLUSH INIT FIND PASS}
%MAN ON
%MAN-TEX:\item[»taboo:« «identifier»...]
This directive instructs \cmix{} to avoid the given identifiers when
it chooses names for local functions and variables in the generating
extension and residual program.

%MAN OFF
This directive is useful if a header file may define macros
or additional functions that you do not want \cmix{} to know about.

%MAN ON
The names of external functions and variables and »visible« variables
are not affected by the »taboo:«
directive. They come out exactly as they appear in \cmix's input,
and if that creates problems, you get to sort out some interesting
error messages from the C compiler.
The same holds for »generator:« entry points.
%MAN OFF

\subsection{Magic constants}
\label{well-known constant}
Some abstract interfaces defines identifiers that should evaluate
to values with a given type without defining what the precise value
is. One example is »stdin«, »stdout«, and »stderr« defined by
»<stdio.h>« to be expressions of type »FILE*« with specified properties.

One way to write an abstract definition for such an identifier
would be
\example{extern FILE *const stderr;}
\example{\#pragma cmix well-known: stderr}
which indeed makes »stderr« be a (pseudo-)rvalue expression of type
»FILE*« and suppresses the declaration in the residual program.

However, there is an unexpected side effect of this. It makes \cmix{}
decide on a single binding for the variable. Thus one cannot have
»stderr« appear at spectime as well as in the residual program.
This would have made good sense, e.g.
\example{\_\_CMIX(spectime)fprintf(stderr,"p-gen went wrong\char`\\n");}
\example{\_\_CMIX(residual)fprintf(stderr,"p-res went wrong\char`\\n");}

This use is made possible with the »well-known constant« annotation:
\example{well-known constant: foo}
%MAN ON
%MAN-TEX:\item[»well-known constant:« «identifier»...]
Whenever \manIgnore{»foo«}
%MAN-TEX:«identifier»
appears in the C source it is treated as a literal constant just
like, \eg, ``»42«'', and copied verbatim to the generating
extension or the residual program (the binding-time analysis
decides which). It is assumed that a header will be included
(with the »header:« directive) that makes the precense of the
identifer there meaningful.

%MAN-TEX:«identifier»
\manIgnore{»foo«} must be declared somewhere in the program as an
»extern« and »const« variable---this declaration supplies the type
of the constant expression and must be in scope whenever it
is used%
%MAN OFF
\footnote{The reason for this convoluted two-step syntax is that
it frees the specializer directive parser from containing a parser
for C types}%
%MAN ON
. The declaration is automatically supressed in the output, and
%MAN-TEX:the «identifier»
\manIgnore{»foo«} is implicitly registered as a »taboo«.
%MAN OFF


%-------------------------------------------------


\subsection{Abstract types}
\label{abstract}
%MAN ON
%MAN%.SH ABSTRACT TYPES
\cmix{} has a special syntax for defining abstract types:
\example{typedef \_\_CMIX(bar) baz ;}
which declares »baz« as an abstract type with the »b«,
»a«, and »r« properties. The type so defined is treated
very like a predefined type such as »signed char«. Syntactically
the abstract type is a ``typedef-name''.

Zero or more of the following property characters can be
specified between the parentheses:
\begin{itemize}
\item[»a«]-- The type is ``arithmetic'': the type checker will allow
  values of this type as operands to arithmetic operators such as
  »+« and »/«, and conversions to and from other arithmetic types.
\item[»i«]-- The type is ``integral'': the type checker allows
  the same operations as for arithmetic types, in addition to
  integer-only operations such as »\%« and »<<«.
\item[»u«]-- The type is ``unsigned'': This is only meaningful
  if the »i« property is given. If lifting of the type
  is required, the value to be lifted will be converted to an
  »unsigned long« and printed to the residual program as such.
\item[»s«]-- The type is ``signed''. This counterpart to
  »u« is currently the default for ``integral'' abstract types
  with no signedness attribute. When lifting the type it gets
  printed as a »long«.
\item[»p«]-- The type is a ``pointer type'': the type checker will
  allow conversions to and from other pointer types.
\end{itemize}
Unrecognized properties such as »b« and »r« are silently ignored.
%MAN OFF

It is expected that »header« directives are used to include headers
that make it legal to use »foo« as a type name in the generating
extension and the residual program.
