Proposed Enhancements to PortAudio API
014 - Implementation Style Guidelines
Enhancement Proposals Index,
PortAudio Home Page
Updated: July 26, 2002
This document provides coding guidelines for PortAudio implementors. Some of the guildelines pertain to mechanical style, others to quality of implementation issues. Since the PortAudio code is commonly edited on many different platforms using different editors these guideline should be followed to improve readability and consistency.
PortAudio API Design Guidelines
The design guidelines of the PortAudio project are restated here
as some of them apply to implementation as well as to API design.
Implementation should be possible on all common computer
Clients of PortAudio should be able to gain efficient,
and ideally optimal use of the audio services
on all target platforms.
The API should be simple enough to be used by music
students with minimal experience in C programming.
The API should seek to provide only low-level audio
services, and to only support those services directly
available on the host platform.
Note that the final guideline has been relaxed with regard to audio
sample formats and user buffer sizes - PortAudio can convert between
a number of sample formats and can adapt to the user's buffer size requirements.
The following formatting conventions should be adhered to in all PortAudio code:
AStyle ( http://astyle.sourceforge.net/ ) has been proposed as helpful tool for cleaning code, however we don't intend to use it on an ongoing basis. It is expected that contributors of each implementation will take responsibility for keeping their code clean.
[META]Provide comment format and style guidelines, since every file seems to use a different
commenting style for no good reason.[/META]
Quality of Implementation Guidelines
The following coding guidelines should be followed in order to establish a quality baseline for our implementations:
- All code should be written in C++-compatible plain ANSI-C (i.e. no // comments). It has been suggested that all implementations should compile silently with both "gcc -ansi -pedantic -Wall" and "g++ -ansi -pedantic -Wall"
- Think of PortAudio as a heavyweight library rather than a lightweight wrapper. Always code defensively. Efficiency is important where it matters (eg in real-time callbacks) but safety is important everywhere.
- All parameters passed to PortAudio by the user should be validated, and error codes returned where necessary. All reasonable efforts should be made to minimise the risk of a crash resulting from passing incorrect parameters to PortAudio.
- Error handling should be complete. Every host function that can return an error condition should have its status checked. PortAudio may attempt to recover from errors in some cases, but generally error codes should be returned to the client.
- In almost all cases, a PortAudio error code should be preferred to returning PaHostError. If a new PortAudio error code is needed it should be discussed with the maintainer to coordinate updating portaudio.h
- PortAudio code should not cause resource leaks. After Pa_Terminate() is called, implementations should guarantee that all dynamically allocated resources have been freed.
- The definition of the PortAudio API should minimise "implementation defined behaviour". For example, calling functions such as Pa_Initialize() after PortAudio is initialised, or Pa_Terminate() after PortAudio has been terminated has well defined behaviour.
- Minimise dependence on ANSI C runtime on platforms where it would have to be loaded separately (eg on Win32 prefer Win32 API functions such as GlobalAlloc() to ANSI C functions such as malloc().)
It has been suggested that we make an effort to minimise the use of global and static data in PortAudio implementations. Another related goal is to reduce name pollution in the global scope. Some possible guidelines in this regard are:
- Implementations should avoid exporting any symbols except where absolutely necessary. Specifically, global data must be declared statically. The next section documents naming conventions for all PortAudio symbols.
- Implementations should minimise their use of static data.
- All #defines begin with PA_
- All #defines local to a file end with _
- All global utility variables begin with paUtil
- All global utility types begin with PaUtil (including function types)
- All global utility functions begin with PaUtil_
- All static variables end with _
- All static constants begin with const and end with _ (eg: constMyMagicNumber_)
- All static funtions have no special prefix/suffix
Platform-specific shared functions should begin with Pa_ where PN is the
platform name. eg. PaWin_ for windows, PaUnix_ for unix.
In general, implementations should declare all of their members static,
except for their initializer which should be exported. All exported names
should be preceeded by Pa_ where is the module name, for example
the windows mme initializer should be named PaWinMme_Initialize().
If it is necessary for implementations to define non-static symbols, they should
use the following naming conventions, where is the module name such as WinMme.
- global variables should begin with pa
- global types should begin with Pa
- global utility functions should begin with Pa_
Debug Message Logging
Two utilities for debug messages are provided. The PA_DEBUG macro defined in
pa_implementation.h provides a simple way to print debug messages to stderr.
Due to real-time performance issues, PA_DEBUG may not be suitable for use
within the portaudio processing callback, or in other threads. In such cases
the event tracing facility provided in pa_trace.h may be more appropriate.
If PA_LOG_API_CALLS is defined, all calls to the public PortAudio API
will be logged to stderr along with parameter and return values.