Commit dd3a4b0d7647da2e5739f791b4595a0886d03e45

Authored by Georg Hopp
1 parent a7a926b7

Improve README.md

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