SAL Library Conventions
Interfaces
The library obeys a strict interface/implementation
distinction. Interface classes specify required functionality;
multiple implementation subclasses of the interface can provide that
functionality in different ways.
Templates
Only containers (e.g. sets, sequences, etc.) are
implemented with templates. The rest of the library relies on
type-casting, which of course can cause trouble if used improperly.
Container templates are generally instantiated with pointer types
(e.g. TSet<Geom *>).
Ops
All functions are passed as instances of subclasses of
template Op classes, which specify the argument and return
types. For example, a volume function would be of type Op_1<Geom
*, double>. A Perl script is provided to make programming with
these classes more pleasing to the eye.
Safety
An object is not required to ensure that a method is
called legally. If you call a method illegally (e.g. ask an ngraph
for the neighbors of an object not in the ngraph), an object can do
whatever it wants (including letting the program dump core).
Eventually we hope to provide checking implementations that
wrap existing implementations with tests for safety. Such
implementations can be used during program design to help debug and
then can easily be removed for faster execution.
Prototypes
Some classes and functions take example
prototype instances, which they will use to create more instances.
For example, to read a collection of geometric objects, you can pass a
single example object; the reader will create and read into multiple
copies of that prototype. In some cases a default exists and a
prototype is only used to tailor the run-time performance of a
program. For example, an ngraph might normally store neighbors in a
set, but allow the user to provide a template so that they can be
stored in a vector instead.
Inheritance
Application code can use subclasses to maintain
additional information or to fine-tune an implementation. For
example, an application could inherit from a particular Geom implementation to store features of that
geometric object. Such subclasses must define the
new_object method to return a new instance. Otherwise nasty bugs will
arise when using prototypes of the implementation.
Garbage Collection
The library is compiled so that instances
are garbage collected. This does not prevent you from using
"delete" wherever you like, if you enjoy doing that.
Ownership
When an object creates another object as the
response to a query, it is assumed still to "own" that object unless
otherwise indicated. In particular, when the creator is destroyed,
the created object can also be destroyed. For example, an ngraph owns
the neighbor sets it returns; when the ngraph is destroyed, those sets
are no longer valid.