3 Library Reference
Much of the code developed for avram may be reusable in other
projects, so it has been packaged into a library and documented in this
chapter. For ease of reference, this chapter is organized with a
separate section for each source file. For the most part, each source
file encapsulates an abstract type and a number of related functions,
except for a few cases where C makes such a design awkward. An attempt
has been made to present the sections in a readable order as far as
possible.
The documentation in this chapter is confined to the application program
interface (API), and does not delve unnecessarily into any details of the
implementation. A reader wishing to extend, modify, or troubleshoot the
library itself can find additional information in the source code
comments. These are more likely to be in sync with the code than this
document may be, and are more readily accessible to someone working with
the code.
Some general points pertaining to the library are the following.
- Unlike the previous chapter, this chapter uses the word
“function” in the C sense rather than the mathematical sense of the word.
- Internal errors are internal from the user's point of view, not
the developer's (Internal Errors). Invoking these functions in
ways that are contrary to their specifications can certainly cause
internal errors (not to mention segfaults).
- The library is definitely not thread safe, and thread safety is
not a planned enhancement. The amount of locking required to make it
thread safe would probably incur an objectionable performance penalty
due to the complexity of the shared data structures involved, in
addition to being very difficult to get right. If you need these
facilities in a concurrent application, consider spawning a process for
each client of the library so as to keep their address spaces separate.
- The library files are built from the standard source
distribution using GNU libtool. In the default directory
hierarchy, they will be found
either in /usr/lib/libavram.* or in /usr/local/lib/libavram.*.
These directories will differ in a non-standard installation.
- The header files will probably be
located in either /usr/include/avm/*.h or
/usr/local/include/avm/*.h for a standard installation.
- All exported functions, macros and constants are
preceded with
avm_, so as to reduce the chance of name clashes
with other libraries. Not all type declarations or field identifiers
follow this convention, because that would be far too tedious.
- The library header files are designed to be compatible with C++
but have been tested only with C. Please refer to platform specific
documentation for further information on how to link library modules
with your own code.