README.html
9.82 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title></title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<h1 id="libtrbase">LIBTRBASE</h1>
<p>As the very basic building block of <a href="http://taskrambler.weird-web-workers.org/">taskrambler</a> 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.</p>
<h3 id="the-class-system">The class system</h3>
<p>The class system is not what you know from "real" object oriented languages. It only provides these few OOP features:</p>
<ul>
<li>code and data encapsulation</li>
<li>late binding through interfaces</li>
<li>inheritance</li>
</ul>
<p>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.</p>
<p>The second important thing, mostly to reduce code duplication, is inheritance.</p>
<p>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.</p>
<p>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.</p>
<p>The ideas for this are partly derived from the Book <em>"Object Oriented Programming in ANSI C"</em> from Axel-Tobias Schreiner.</p>
<p>In the examples I will show how libtrbase supports you in creating these structures.</p>
<h3 id="the-optimized-memory-management">The optimized memory management</h3>
<p>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.</p>
<p>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.</p>
<p>For the ballanced btree I use red-black trees. Thanks to the authors of the <a href="http://en.wikipedia.org/wiki/Red–black_tree">Wikipedia article</a>. This implementation is more or less taken from there, with only some small changes here and there.</p>
<p>The idea is based on an idea found on <a href="http://www.flounder.com/memory_allocation.htm">this page</a> 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.</p>
<h2 id="installation">INSTALLATION</h2>
<p>This can be installed via the usual configure, make, make install cycle. For gentoo users am ebuild is added under docs.</p>
<h3 id="api-doc">API DOC</h3>
<p>To generate the api doc a patched version of doxygen is neccessary. A patch is included under docs.</p>
<p><code>make docs</code> creates the api doc.</p>
<h3 id="test-coverage-report">TEST COVERAGE REPORT</h3>
<p>gcov and lcov are needed to build these.</p>
<p>The source has to be configured with <code>configure --enable-gcov</code>. <code>make coverage-html</code> creates the converage reports then.</p>
<h2 id="usage">USAGE</h2>
<h3 id="api">API</h3>
<p>The public API consists of several preprocessor macros and some functions. When you look through the code you will find other symbols (functions or macros) which might seem useful. Here I try to focus on the neccessaties for using the library.</p>
<h4 id="function-like-macros---class-creation">function-like macros - class creation</h4>
<ul>
<li><code>TR_CLASS(name)</code>: Declare a new class.</li>
<li><code>TR_CREATE_CLASS(name, parent, ...)</code>: Create a new class.</li>
<li><code>TR_EXTENDS(parent)</code>: Extend another class</li>
</ul>
<h4 id="function-like-macros---class-information">function-like macros - class information</h4>
<ul>
<li><code>TR_GET_CLASS(object)</code>: Get the class of the given object.</li>
<li><code>TR_HAS_PARENT(class)</code>: Check if the class extends another class.</li>
<li><code>TR_IS_OBJECT(obj)</code>: Check that the given pointer is really an instance of a class.</li>
<li><code>TR_INSTANCE_OF(class, obj)</code>: Check that the given obj is an instance of class.</li>
</ul>
<h4 id="function-like-macros---interface-selector-helper">function-like macros - interface selector helper</h4>
<ul>
<li><code>TR_CALL(object, iface, method, ...)</code>: Call the interface implementation of the class or one of the parent classes of object.</li>
<li><code>TR_RETCALL(object, iface, method, ret, ...)</code>: Same as TR_CALL but with return value.</li>
<li><code>TR_PARENTCALL(object, iface, method, ...)</code>: Directly call the implementation within the parent class.</li>
</ul>
<h4 id="function-like-macros---interface-creation">function-like macros - interface creation</h4>
<ul>
<li><code>TR_INTERFACE(name)</code>: Declare a new inerface.</li>
<li><code>TR_CREATE_INTERFACE(name, nfunc)</code>: Create the new interface.</li>
<li><code>TR_INIT_IFACE(name, ...)</code>: Create an interface implementation and assign functions to it.</li>
<li><code>TR_IF(name)</code>: Convenience for getting an interface implementation by name. Used when assigning an interface to a class.</li>
</ul>
<h4 id="function-like-macros-for-the-class-interface">function-like macros for the class interface</h4>
<p>The valious constructor and destructors are also assigned to an interface. The is the only interface every class MUST have so that instances can be created and destroyed. At least a constructor and a destructor must be assigned to this interface. The following selectors then utilize the interface to create and destroy instances.</p>
<ul>
<li><code>TR_new(class, ...)</code>: Create a new instance of a class with a variable argument list for the constructor interface.</li>
<li><code>TR_newv(class, args)</code>: Same as <em>TR_new</em> but accepts a va_list* for the constructor arguments.</li>
<li><code>TR_delete(object)</code>: Destroy an instance.</li>
<li><code>TR_clone(object)</code>: Call an constructor that accepts another instance to create a clone from this instance.</li>
</ul>
<h4 id="selector-functions-subjectobserver-interface">selector functions subject/observer interface</h4>
<p>These are in fact two interfaces that can be used to implement the subject/observer design pattern.</p>
<ul>
<li><code>TR_subjectAttach(Subject, Observer)</code>: Add an observer to a subject. The concrete implementation has to take care of memory management etc.</li>
<li><code>TR_subjectDetach(Subject, Observer)</code>: Remove an observer from a subject.</li>
<li>`TR_notify(Subject):* Notify all registered observer of an event.</li>
<li><code>TR_observerUpdate(Observer, Subject)</code>: This must be called in TR_subjectNotify to inform a registered observer of an event.</li>
</ul>
<h4 id="selector-functions-indexable-interface">selector functions indexable interface</h4>
<ul>
<li><code>TR_getIndex(Indexable)</code>: Get a unique index of an instance. How this is created is subject of the concrete implementation.</li>
</ul>
<h4 id="selector-functions">selector functions</h4>
<ul>
<li><code>TR_serializedSize(Serializable)</code>: Get the size of the serialized instance.</li>
<li><code>TR_serialize(Serializable, unsigned char * serialized)</code>: Serialize the instance into the serialized buffer. The buffer has to be large enough to hold the serialized instance.</li>
<li><code>TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)</code>: Initialize the instance with the serialized data stored in serialized.</li>
</ul>
<h4 id="memory-management---functions">memory management - functions</h4>
<ul>
<li><code>void * TR_malloc(size_t)</code>:</li>
<li><code>void * TR_calloc(size_t, size_t)</code>:</li>
<li><code>void * TR_reference(void *)</code>:</li>
<li><code>size_t TR_getSize(void *)</code>:</li>
<li><code>void TR_cleanup()</code>:</li>
</ul>
<h4 id="memory-management---macros">memory management - macros</h4>
<ul>
<li><code>TR_MEM_FREE(seg)</code>:</li>
</ul>
<h3 id="example">EXAMPLE</h3>
<h4 id="optimized-memory-management">optimized memory management</h4>
<h4 id="create-a-new-class">create a new class</h4>
<h4 id="create-a-new-interface">create a new interface</h4>
<h4 id="implement-an-interface-in-a-class">implement an interface in a class</h4>
<h4 id="class-extension">class extension</h4>
<h2 id="testing">TESTING</h2>
<p>This comes with the start of a unit test suite. You can use <em>make test</em> to build and run the existent tests.</p>
<h3 id="requirements">REQUIREMENTS</h3>
<p>Currently, you need valgrind to build the tests, because some memory checking is done by the way.</p>
<h2 id="contribution">CONTRIBUTION</h2>
<p>I would really like to see some people possibly interested in this stuff. I think it contains some really interesting ideas.</p>
<p>If you like to contribute anyway, make a fork, do your changes and generate a pull request. Or simply contact me on georg@steffers.org.</p>
</body>
</html>