Showing
1 changed file
with
57 additions
and
141 deletions
1 | -LIBTRBASE | |
2 | -========= | |
1 | +# Libtrbase | |
3 | 2 | |
4 | 3 | As the very basic building block of |
5 | -[taskrambler](http://taskrambler.weird-web-workers.org/) this library | |
6 | -provides a system to create basic classes and interfaces in | |
4 | +[taskrambler](https://gitlab.weird-web-workers.org/taskrambler/taskrambler) | |
5 | +this library provides a system to create basic classes and interfaces in | |
7 | 6 | ANSI C, some common macro definitions (always useful) and an optimized |
8 | 7 | memory management system. |
9 | 8 | |
10 | -### Links | |
11 | - * See the latest coverage report [here](http://ci-build.weird-web-workers.org/trbase/coverage_latest/). | |
12 | - * The generated API doc can be found [here](http://ci-build.weird-web-workers.org/trbase/api_latest/). | |
13 | - * You can download a version [here](http://ci-build.weird-web-workers.org/trbase/artifacts/). | |
9 | +## Synopsis | |
14 | 10 | |
15 | -### The class system ### | |
11 | +All prototypes can be included with: | |
12 | + | |
13 | +```C | |
14 | +#include <trbase.h> | |
15 | + | |
16 | +... | |
17 | +``` | |
18 | + | |
19 | +Link your code against the library: ```gcc -ltrbase ...```. | |
20 | + | |
21 | +## Description | |
22 | + | |
23 | +### The class system | |
16 | 24 | |
17 | 25 | The class system is not what you know from "real" object oriented languages. |
18 | 26 | It only provides these few OOP features: |
... | ... | @@ -46,7 +54,7 @@ The ideas for this are partly derived from the Book |
46 | 54 | In the examples I will show how libtrbase supports you in creating these |
47 | 55 | structures. |
48 | 56 | |
49 | -### The optimized memory management ### | |
57 | +### The optimized memory management | |
50 | 58 | |
51 | 59 | Allocating and freeing memory on the heap is an expensive action. And because |
52 | 60 | of fragmentation effects it might become even more expensive if the process |
... | ... | @@ -70,151 +78,59 @@ The Joseph M. Newcomer Co. |
70 | 78 | The concrete idea was first described by Charles B. Weinstock in his Ph.D. |
71 | 79 | dissertation on storage allocation. |
72 | 80 | |
73 | -INSTALLATION | |
74 | ------------- | |
75 | - | |
76 | -This can be installed via the usual configure, make, make install | |
77 | -cycle. For gentoo users am ebuild is added under docs. | |
78 | - | |
79 | -### API DOC ### | |
80 | - | |
81 | -To generate the api doc a patched version of doxygen is | |
82 | -neccessary. A patch is included under docs. | |
83 | - | |
84 | -`make docs` creates the api doc. | |
85 | - | |
86 | -### TEST COVERAGE REPORT | |
87 | - | |
88 | -gcov and lcov are needed to build these. | |
89 | - | |
90 | -The source has to be configured with `configure --enable-gcov`. | |
91 | -`make coverage-html` creates the converage reports then. | |
92 | - | |
93 | - | |
94 | -USAGE | |
95 | ------ | |
96 | - | |
97 | -### API ### | |
98 | - | |
99 | -The public API consists of several preprocessor macros and some functions. | |
100 | -When you look through the code you will find other symbols (functions or | |
101 | -macros) which might seem useful. Here I try to focus on the neccessaties | |
102 | -for using the library. | |
103 | - | |
104 | -#### function-like macros - class creation #### | |
105 | - | |
106 | -* `TR_CLASS(name)`: Declare a new class. | |
107 | -* `TR_CREATE_CLASS(name, parent, ...)`: Create a new class. | |
108 | -* `TR_EXTENDS(parent)`: Extend another class | |
109 | - | |
110 | -#### function-like macros - class information #### | |
81 | +### Installation | |
111 | 82 | |
112 | -* `TR_GET_CLASS(object)`: Get the class of the given object. | |
113 | -* `TR_HAS_PARENT(class)`: Check if the class extends another class. | |
114 | -* `TR_IS_OBJECT(obj)`: Check that the given pointer is really an | |
115 | - instance of a class. | |
116 | -* `TR_INSTANCE_OF(class, obj)`: Check that the given obj is an instance of | |
117 | - class. | |
83 | +This can be installed via the usual configure, make, make install cycle. For | |
84 | +gentoo users am ebuild is added under docs. | |
118 | 85 | |
119 | -#### function-like macros - interface selector helper #### | |
86 | +### Documentation | |
120 | 87 | |
121 | -* `TR_CALL(object, iface, method, ...)`: Call the interface implementation | |
122 | - of the class or one of the parent classes of object. | |
123 | -* `TR_RETCALL(object, iface, method, ret, ...)`: Same as TR\_CALL but | |
124 | - with return value. | |
125 | -* `TR_PARENTCALL(object, iface, method, ...)`: Directly call the | |
126 | - implementation within the parent class. | |
88 | +* The API doc can be found | |
89 | + [here](http://ci-build.weird-web-workers.org/trbase/api_latest/). | |
90 | +* See the latest coverage report | |
91 | + [here](http://ci-build.weird-web-workers.org/trbase/coverage_latest/). | |
92 | +* You may have a look in our WIKI | |
93 | + [here](https://gitlab.weird-web-workers.org/taskrambler/trbase/wikis/home). | |
127 | 94 | |
128 | -#### function-like macros - interface creation #### | |
95 | +## Requirements | |
129 | 96 | |
130 | -* `TR_INTERFACE(name)`: Declare a new inerface. | |
131 | -* `TR_CREATE_INTERFACE(name, nfunc)`: Create the new interface. | |
132 | -* `TR_INIT_IFACE(name, ...)`: Create an interface implementation and assign | |
133 | - functions to it. | |
134 | -* `TR_IF(name)`: Convenience for getting an interface implementation by name. | |
135 | - Used when assigning an interface to a class. | |
97 | +### Buildtime | |
136 | 98 | |
137 | -#### function-like macros for the class interface #### | |
138 | -The valious constructor and destructors are also assigned to an interface. The | |
139 | -is the only interface every class MUST have so that instances can be created and | |
140 | -destroyed. At least a constructor and a destructor must be assigned to this | |
141 | -interface. The following selectors then utilize the interface to create and | |
142 | -destroy instances. | |
99 | +#### required | |
143 | 100 | |
144 | -* `TR_new(class, ...)`: Create a new instance of a class with a variable | |
145 | - argument list for the constructor interface. | |
146 | -* `TR_newv(class, args)`: Same as *TR_new* but accepts a va_list* for the | |
147 | - constructor arguments. | |
148 | -* `TR_delete(object)`: Destroy an instance. | |
149 | -* `TR_clone(object)`: Call an constructor that accepts another instance to | |
150 | - create a clone from this instance. | |
101 | + * A C compiler & Tools. | |
151 | 102 | |
152 | -#### selector functions subject/observer interface #### | |
153 | -These are in fact two interfaces that can be used to implement the | |
154 | -subject/observer design pattern. | |
103 | +#### optional | |
155 | 104 | |
156 | -* `TR_subjectAttach(Subject, Observer)`: Add an observer to a subject. The | |
157 | - concrete implementation has to take care of memory management etc. | |
158 | -* `TR_subjectDetach(Subject, Observer)`: Remove an observer from a subject. | |
159 | -* `TR_notify(Subject):* Notify all registered observer of an event. | |
160 | -* `TR_observerUpdate(Observer, Subject)`: This must be called in | |
161 | - TR_subjectNotify to inform a registered observer of an event. | |
105 | + * `lcov`: To generate test coverage reports. | |
106 | + * `doxygen`: For API doc creation. | |
107 | + * `valgrind`: For memory checks. | |
162 | 108 | |
163 | -#### selector functions indexable interface #### | |
109 | +## Contributing | |
164 | 110 | |
165 | -* `TR_getIndex(Indexable)`: Get a unique index of an instance. How this is | |
166 | - created is subject of the concrete implementation. | |
167 | - | |
168 | -#### selector functions #### | |
169 | - | |
170 | -* `TR_serializedSize(Serializable)`: Get the size of the serialized instance. | |
171 | -* `TR_serialize(Serializable, unsigned char * serialized)`: Serialize the | |
172 | - instance into the serialized buffer. The buffer has to be large enough to | |
173 | - hold the serialized instance. | |
174 | -* `TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)`: | |
175 | - Initialize the instance with the serialized data stored in serialized. | |
176 | - | |
177 | -#### memory management - functions #### | |
178 | - | |
179 | -* `void * TR_malloc(size_t)`: | |
180 | -* `void * TR_calloc(size_t, size_t)`: | |
181 | -* `void * TR_reference(void *)`: | |
182 | -* `size_t TR_getSize(void *)`: | |
183 | -* `void TR_cleanup()`: | |
184 | - | |
185 | -#### memory management - macros #### | |
186 | - | |
187 | -* `TR_MEM_FREE(seg)`: | |
188 | - | |
189 | - | |
190 | -### EXAMPLE ### | |
191 | - | |
192 | -#### optimized memory management #### | |
193 | - | |
194 | -#### create a new class #### | |
195 | - | |
196 | -#### create a new interface #### | |
197 | - | |
198 | -#### implement an interface in a class #### | |
199 | - | |
200 | -#### class extension #### | |
201 | - | |
202 | -TESTING | |
203 | -------- | |
111 | +I would really like to see some people possibly interested in this stuff. | |
112 | +I think it contains some really interesting ideas. | |
204 | 113 | |
205 | -This comes with the start of a unit test suite. | |
206 | -You can use *make test* to build and run the existent tests. | |
114 | +If you like to contribute, contact me via email. You are free to clone | |
115 | +and play with this code. | |
207 | 116 | |
208 | -### REQUIREMENTS | |
117 | +## License | |
209 | 118 | |
210 | -Currently, you need valgrind to build the tests, because some memory checking | |
211 | -is done by the way. | |
119 | +GNU General Public License (Version 3) | |
212 | 120 | |
213 | -CONTRIBUTION | |
214 | ------------- | |
121 | +> This program is free software: you can redistribute it and/or modify | |
122 | +> it under the terms of the GNU General Public License as published by | |
123 | +> the Free Software Foundation, either version 3 of the License, or | |
124 | +> (at your option) any later version. | |
125 | +> | |
126 | +> This program is distributed in the hope that it will be useful, | |
127 | +> but WITHOUT ANY WARRANTY; without even the implied warranty of | |
128 | +> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
129 | +> GNU General Public License for more details. | |
130 | +> | |
131 | +> You should have received a copy of the GNU General Public License | |
132 | +> along with this program. If not, see <http://www.gnu.org/licenses/>. | |
215 | 133 | |
216 | -I would really like to see some people possibly interested in this stuff. | |
217 | -I think it contains some really interesting ideas. | |
134 | +## Author | |
218 | 135 | |
219 | -If you like to contribute anyway, make a fork, do your changes and generate | |
220 | -a pull request. Or simply contact me on georg@steffers.org. | |
136 | +Georg Hopp <<georg@steffers.org>> | ... | ... |
Please
register
or
login
to post a comment