Re: How to Design an Application Programmers' Interface (API)

["E. Robert Tisdale" <edwin@netwood.net>]

The ANSI C computer programming language
does not support Object Oriented Programming very well.
It has an encapsulation mechanism (struct) for creating new types
and a mechanism (typedef) for creating synonyms for existing types
but it doesn't really provide any mechanism
for hiding the data members of a struct except for opaque data types.
The definition of an opaque data type
is never exposed to the application program
so the only way to create, manipulate and destroy opaque data types
is by passing pointers to library functions.
This means that memory for all opaque data types
must be allocated from free storage (on the heap)
which can involve significant overhead for small objects.
Another, less effective, method
for hiding the private data members of a struct in ANSI C
is to provide the application program with a dummy type definition

        typedef struct {
          int dummy[new_type_size/sizeof(int)];
          } new_type;

which is the same size as the new type
but conceals the name and location of all private data members.
The advantage of dummy type definitions is that memory for them
may be allocated from automatic storage (on the stack)
with virtually no overhead.

The problem with opaque data types and dummy type definitions is that
none of the functions that create, manipulate and destroy them
can be implemented as inline functions or C preprocessor macros.
This problem is solved by using library functions
together with opaque data types or dummy type definitions
during program development, debugging and testing
then, just before placing the application into service,
the private type definition is substituted
for the opaque or dummy data type definition,
the inline functions and/or C processor macros are substituted
for the external library functions
and the application program is recompiled.
The advantage of using the external library functions
during application program development, debugging and testing
is that application programs usually compile faster
if they don't need to process inline functions or C preprocessor macros
and the compiler can diagnose programming errors more precisely.

Application programmers must NOT be obliged
to access private data members directly.
The library must provide functions
which application programmers can use
to create, manipulate and destroy objects as efficiently as possible.

If the library API fails to specify such functions
and programmers write applications
which access private data members directly,
library developers will never be able to change
the actual data representation,
the meaning of any data member
or even the name of any data member
without breaking existing application programs.
But, if the library API specifies such functions
and library developers make a reasonable attempt
to hide the actual type definition and private data members
so that applications programmers can't access them directly by accident,
then library developers are at liberty to change the data representation,
including the meaning, location, name and number of data members
at any time just by redefining the library functions
that access them directly and redistributing the library.