\chapter{MALOC Programmer\textquotesingle{}s Guide }
\label{index}\index{MALOC Programmer\textquotesingle{}s Guide@{MALOC Programmer\textquotesingle{}s Guide}}
\begin{center}  \end{center} 

\begin{center} FETK was written by Michael Host.~\newline
 Additional contributing authors are listed in the code documentation. \end{center} 

\DoxyHorRuler{0}
 \doxysection{Table of Contents}\label{index_toc}

\begin{DoxyItemize}
\item \doxysectref{Introduction}{p.}{index_intro}{1} 
\item \doxysectref{Coding Style}{p.}{index_style}{1} 
\item \doxysectref{Application programming interface documentation}{p.}{index_api}{1} 
\begin{DoxyItemize}
\item {\texttt{Modules}} 
\item {\texttt{Class list}} 
\item {\texttt{Class members}} 
\item {\texttt{Class methods}} 
\end{DoxyItemize}
\item \doxysectref{License}{p.}{index_license}{1} 
\end{DoxyItemize}

{\itshape  NOTE\+: } This documentation provides information about the programming interface provided by the MALOC software and a general guide to linking to the MALOC libraries. Information about installation, configuration, and general usage can be found in the {\texttt{User\textquotesingle{}s Guide}}. \DoxyHorRuler{0}
\doxysection{Introduction}\label{index_intro}
MALOC (Minimal Abstraction Layer for Object-\/oriented C) was written by {\texttt{Michael Holst}} at Caltech and UC San Diego, primarily as a portability layer for {\texttt{FETK}} (the Finite Element Took\+Kit).\doxysection{Clean OO C Formalism}\label{index_formalism}
MALOC was written in {\texttt{Clean OO C}}, which is a self-\/imposed disciplined coding formalism for producing object-\/oriented ANSI/\+Standard C which can be compiled with either a C or C++ compiler. We will briefly describe the formalism here (borrowing from N. Baker\textquotesingle{}s nice description in the APBS documentation).

Clean OO C formalism requires that all public data is enclosed in structures which resemble C++ classes. These structures and member functions are then declared in a public header file which provides a concise description of the interface (or API) for the class. Private functions and data are included in private header files (or simply the source code files themselves) which are not visible generally visible (data encapsulation). When using the library, the user only sees the public header file and the compiled library and is therefore (hopefully) oblivious to the private members and functions. Each class is also equipped with a constructor and destructor function which is responsible for allocating and freeing any memory required by the instatiated objects.

Public data members are enclosed in C structures which are visible to the library user. Public member functions are generated by mangling the class and function names and passing a pointer to the object on which the member function is supposed to act. For example, a public member function with the C++ declaration 
\begin{DoxyPre}
    public double Foo::bar(int i, double d)
    \end{DoxyPre}
 would be declared as 
\begin{DoxyPre}
    double Foo\_bar(Foo *thee, int i, double d)
    \end{DoxyPre}
 where {\ttfamily VEXTERNC} is a compiler-\/dependent macro, the underscore {\ttfamily \+\_\+} replaces the C++ double-\/colon {\ttfamily \+::}, and {\ttfamily thee} replaces the {\ttfamily this} variable implicit in all C++ classes. Since they do not appear in public header files, private functions could be declared in any format pleasing to the user, however, the above declaration convention should generally be used for both public and private functions. Within the source code, the public and private function declarations/definitions are prefaced by the macros {\ttfamily VPUBLIC} and {\ttfamily VPRIVATE}, respectively. These are macros which reduce global name pollution, similar to encapsulating private data withing C++ classes.

The only C++ functions not explicitly covered by the above declaration scheme are the constructors (used to allocate and initialize class data members) and destructors (used to free allocated memory). These are declared in the following fashion\+: a constructor with the C++ declaration 
\begin{DoxyPre}
     public void Foo::Foo(int i, double d)
     \end{DoxyPre}
 would be declared as 
\begin{DoxyPre}
      Foo* Foo\_ctor(int i, double d)
      \end{DoxyPre}
 which returns a pointer to the newly constructed {\ttfamily Foo} object. Likewise, a destructor declared as 
\begin{DoxyPre}
      public void Foo::\string~Foo()
      \end{DoxyPre}
 in C++ would be 
\begin{DoxyPre}
      void Foo\_dtor(Foo **thee)
      \end{DoxyPre}
 in Clean OO C. 

Finally, inline functions in C++ are simply treated as macros in Clean OO C and declared/defined using "{}\#define"{} statements in the public header file. See any of the MALOC header files for more examples on the Clean OO C formalism.\doxysection{Coding Style}\label{index_style}
The best (and most entertaining) description of a C coding style that is very close to what I use in MALOC is that described by Linus Torvalds in his "{}\+Coding\+Style"{} file in the Linux kernel sources (usually found in the file "{}/usr/src/linux/\+Documentation/\+Coding\+Style"{} on any Linux box). He describes a coding style that is modular, completely documented (but in a spartan way), and very practical.

Below are some additional notes on the coding style I use in MALOC beyond what Torvalds describes. These additional guidelines are mostly concerned with being compatible with the Clean OO C dialect, giving an object-\/oriented look and feel to MALOC. 
\begin{DoxyItemize}
\item Tabs and spaces ==$>$ Probably the most important rule\+: NO TABS! 

Use ONLY SPACES, NO TABS, in source code. When indenting a code block, ALWAYS USE EXACT 4 SPACES, no more, no less. While this single anal rule seems excessive, in my experience it is the single most useful code formatting guideline one can impose, in terms of producing code written by many different developers that can be read and understood quickly by other developers using the same convention. If four spaces (rather than two or three) forces you to use more than 80 columns for nesting loops/etc, then your routine is too complex to be read by someone else anyway and it should be split into two or more routines. 


\item ALLCAPS ==$>$ A "{}\#define"{}d constant or a macro. Examples\+: 
\begin{DoxyPre}
      "{}\#define"{} VTRUE    1
      "{}\#define"{} VFALSE   0
      "{}\#define"{} \doxyref{VABS(x)}{p.}{a00002_a6a6283ab8af6569d4955242614b9427b}  ((x) >= 0 ? (x) : -\/(x))
      \end{DoxyPre}
 
\item Upper\+Mixed ==$>$ Class name, or class constructor or destructor. Examples\+: 


\begin{DoxyPre}
      C++:     class Mesh \{ ... \};
               Mesh(void) \{ ... \}
               \string~Mesh(void) \{ ... \}

      Clean C: typedef struct Mesh \{ ... \} Mesh;
               void Mesh\_ctor(Mesh *thee) \{ ... \}
               void Mesh\_dtor(Mesh *thee) \{ ... \}
      \end{DoxyPre}
 NOTE\+: The "{}this"{} pointer is implicitly used in C++. We simulate this coding style with the "{}thee"{} pointer in Clean C. By using a name different than "{}this"{}, we continue to have a legal C++ program. 


\item lower\+Mixed ==$>$ A class member function or generic function. Examples\+: 


\begin{DoxyPre}
      C++:    Class Mesh \{
                 ...
                 void print(void) \{ ... \}
                 ...
              \}
              void Mesh::plot(void) \{ ... \}

      Clean C: void Mesh\_print(Mesh *thee) \{ ... \}
               void Mesh\_plot(Mesh *thee) \{ ... \}
      \end{DoxyPre}
 
\item \+\_\+private data ==$>$ Pre-\/fixed with an underscore, such as\+: vint \+\_\+dim. 

I don\textquotesingle{}t always adhere to this, but it helps make it clear when you are doing something unsafe with private data that you should have written an accessor member function to handle. (UPDATE\+: I no longer allow this practice in MALOC, because symbols beginning with an underscore often conflict with internal compiler symbols in GCC and other ANSI-\/C compilers.) 
\item Datatypes ==$>$ Use only standard or compatible datatypes. 

Beyond the stuctures used to define classes, only standard datatypes are used as primitive types in MALOC, such as char, int, float, and double. 


\item Core structures ==$>$ Refer to headers vel.\+h and ves.\+h in the GEM library for examples. 


\item Other comments ==$>$ We basically adhere to the GNU coding conventions, except that Richard Stallman recommends (in his GNU Coding Standards paper) writing blocks as follows\+: 
\begin{DoxyPre}
      if (cond)
      \{
      \}
      \end{DoxyPre}
 whereas I find the following usually more readable\+: 
\begin{DoxyPre}
      if (cond) \{
      \}
      \end{DoxyPre}
 However, for complete routines I do follow Richard\textquotesingle{}s approach\+: 
\begin{DoxyPre}
      void func(void)
      \{
          ...stuff...
      \}
      \end{DoxyPre}
 If something is very simple then I break all rules\+: 
\begin{DoxyPre}
      int myId(void) \{ return id; \}
      \end{DoxyPre}
 
\end{DoxyItemize}\doxysection{Application programming interface documentation}\label{index_api}
The API documentation for this code was generated by {\texttt{doxygen}}. You can either view the API documentation by using the links at the top of this page, or the slight re-\/worded/re-\/interpreted list below\+: 
\begin{DoxyItemize}
\item {\texttt{Class overview}} 
\item {\texttt{Class declarations}} 
\item {\texttt{Class members}} 
\item {\texttt{Class methods}} 
\end{DoxyItemize}\doxysection{License}\label{index_license}
\begin{DoxyVerb}   MALOC = < Minimal Abstraction Layer for Object-oriented C >                                               
   Copyright (C) 1994-- Michael Holst                                                                    

   This library is free software; you can redistribute it and/or                                             
   modify it under the terms of the GNU Lesser General Public                                                
   License as published by the Free Software Foundation; either                                              
   version 2.1 of the License, or (at your option) any later version.                                        

   This library is distributed in the hope that it will be useful,                                           
   but WITHOUT ANY WARRANTY; without even the implied warranty of                                            
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU                                          
   Lesser General Public License for more details.                                                           

   You should have received a copy of the GNU Lesser General Public                                          
   License along with this library; if not, write to the Free Software                                       
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA                                   
\end{DoxyVerb}
 