README.md



Libtrbase

As the very basic building block of
taskrambler
this library provides a system to create basic classes and interfaces in
ANSI C, some common macro definitions (always useful) and an optimized
memory management system.


Synopsis

All prototypes can be included with:

#include <trbase.h>

...


Link your code against the library: gcc -ltrbase ....


Description


The class system

The class system is not what you know from "real" object oriented languages.
It only provides these few OOP features:


code and data encapsulation
late binding through interfaces
inheritance


I created it with the idea that at least for me the most useful part
of object orientation is the ability to create interfaces and bind them
to a specific data structure. This binding in turn enables injection which
for me is by far the most important type of object combination.

The second important thing, mostly to reduce code duplication, is inheritance.

The class system combines C structures with one or more interfaces. Each
of these interfaces consists of one ore more pointers to functions which
must be set during the class creation. These functions are then called
via selector functions which have to be defined for the specific interface.

The interface of the class system consists of Preprocessor definitions
which provide an easy way to create the neccessary data structures and
definitions. There are also definitions for calling the correct interface
implementation for a given class instance. If no implementation can be found in
the class of the current object it will be looked for in the parent class
if there is one and so forth.

The ideas for this are partly derived from the Book
"Object Oriented Programming in ANSI C" from Axel-Tobias Schreiner.

In the examples I will show how libtrbase supports you in creating these
structures.


The optimized memory management

Allocating and freeing memory on the heap is an expensive action. And because
of fragmentation effects it might become even more expensive if the process
runs really long.

To overcome this issue I implemented a memory management which never really
free's a given memory region, instead it stores the address in a ballanced btree
indexed by the size of the memory segment. Multiple adresses for memory of the
same size are simply listed. The next allocation first looks in this btree if 
there is a fitting segment (same size or larger as the requested segment) and
returns it if available.

For the ballanced btree I use red-black trees. Thanks to the authors of the
Wikipedia article. This
implementation is more or less taken from there, with only some small changes
here and there.

The idea is based on an idea found on
this page of the
The Joseph M. Newcomer Co.
The concrete idea was first described by Charles B. Weinstock in his Ph.D.
dissertation on storage allocation.


Installation

This can be installed via the usual configure, make, make install cycle. For
gentoo users am ebuild is added under docs.


Documentation


The API doc can be found
here.
See the latest coverage report
here.
You may have a look in our WIKI
here.


Requirements


Buildtime


required


A C compiler & Tools.


optional


lcov: To generate test coverage reports.

doxygen: For API doc creation.

valgrind: For memory checks.


Contributing

I would really like to see some people possibly interested in this stuff.
I think it contains some really interesting ideas.

If you like to contribute, contact me via email. You are free to clone
and play with this code.


License

GNU General Public License (Version 3)


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

This program 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 General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see http://www.gnu.org/licenses/.


Author

Georg Hopp <georg@steffers.org>