From dd3a4b0d7647da2e5739f791b4595a0886d03e45 Mon Sep 17 00:00:00 2001 From: Georg Hopp Date: Sat, 26 Mar 2016 22:56:48 +0100 Subject: [PATCH] Improve README.md --- README.md | 198 ++++++++++++++++-------------------------------------- 1 file changed, 57 insertions(+), 141 deletions(-) diff --git a/README.md b/README.md index 27544e4..4653d4b 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,26 @@ -LIBTRBASE -========= +# Libtrbase As the very basic building block of -[taskrambler](http://taskrambler.weird-web-workers.org/) this library -provides a system to create basic classes and interfaces in +[taskrambler](https://gitlab.weird-web-workers.org/taskrambler/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. -### Links - * See the latest coverage report [here](http://ci-build.weird-web-workers.org/trbase/coverage_latest/). - * The generated API doc can be found [here](http://ci-build.weird-web-workers.org/trbase/api_latest/). - * You can download a version [here](http://ci-build.weird-web-workers.org/trbase/artifacts/). +## Synopsis -### The class system ### +All prototypes can be included with: + +```C +#include + +... +``` + +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: @@ -46,7 +54,7 @@ The ideas for this are partly derived from the Book In the examples I will show how libtrbase supports you in creating these structures. -### The optimized memory management ### +### 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 @@ -70,151 +78,59 @@ 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. - -### API DOC ### - -To generate the api doc a patched version of doxygen is -neccessary. A patch is included under docs. - -`make docs` creates the api doc. - -### TEST COVERAGE REPORT - -gcov and lcov are needed to build these. - -The source has to be configured with `configure --enable-gcov`. -`make coverage-html` creates the converage reports then. - - -USAGE ------ - -### API ### - -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. - -#### function-like macros - class creation #### - -* `TR_CLASS(name)`: Declare a new class. -* `TR_CREATE_CLASS(name, parent, ...)`: Create a new class. -* `TR_EXTENDS(parent)`: Extend another class - -#### function-like macros - class information #### +### Installation -* `TR_GET_CLASS(object)`: Get the class of the given object. -* `TR_HAS_PARENT(class)`: Check if the class extends another class. -* `TR_IS_OBJECT(obj)`: Check that the given pointer is really an - instance of a class. -* `TR_INSTANCE_OF(class, obj)`: Check that the given obj is an instance of - class. +This can be installed via the usual configure, make, make install cycle. For +gentoo users am ebuild is added under docs. -#### function-like macros - interface selector helper #### +### Documentation -* `TR_CALL(object, iface, method, ...)`: Call the interface implementation - of the class or one of the parent classes of object. -* `TR_RETCALL(object, iface, method, ret, ...)`: Same as TR\_CALL but - with return value. -* `TR_PARENTCALL(object, iface, method, ...)`: Directly call the - implementation within the parent class. +* The API doc can be found + [here](http://ci-build.weird-web-workers.org/trbase/api_latest/). +* See the latest coverage report + [here](http://ci-build.weird-web-workers.org/trbase/coverage_latest/). +* You may have a look in our WIKI + [here](https://gitlab.weird-web-workers.org/taskrambler/trbase/wikis/home). -#### function-like macros - interface creation #### +## Requirements -* `TR_INTERFACE(name)`: Declare a new inerface. -* `TR_CREATE_INTERFACE(name, nfunc)`: Create the new interface. -* `TR_INIT_IFACE(name, ...)`: Create an interface implementation and assign - functions to it. -* `TR_IF(name)`: Convenience for getting an interface implementation by name. - Used when assigning an interface to a class. +### Buildtime -#### function-like macros for the class interface #### -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. +#### required -* `TR_new(class, ...)`: Create a new instance of a class with a variable - argument list for the constructor interface. -* `TR_newv(class, args)`: Same as *TR_new* but accepts a va_list* for the - constructor arguments. -* `TR_delete(object)`: Destroy an instance. -* `TR_clone(object)`: Call an constructor that accepts another instance to - create a clone from this instance. + * A C compiler & Tools. -#### selector functions subject/observer interface #### -These are in fact two interfaces that can be used to implement the -subject/observer design pattern. +#### optional -* `TR_subjectAttach(Subject, Observer)`: Add an observer to a subject. The - concrete implementation has to take care of memory management etc. -* `TR_subjectDetach(Subject, Observer)`: Remove an observer from a subject. -* `TR_notify(Subject):* Notify all registered observer of an event. -* `TR_observerUpdate(Observer, Subject)`: This must be called in - TR_subjectNotify to inform a registered observer of an event. + * `lcov`: To generate test coverage reports. + * `doxygen`: For API doc creation. + * `valgrind`: For memory checks. -#### selector functions indexable interface #### +## Contributing -* `TR_getIndex(Indexable)`: Get a unique index of an instance. How this is - created is subject of the concrete implementation. - -#### selector functions #### - -* `TR_serializedSize(Serializable)`: Get the size of the serialized instance. -* `TR_serialize(Serializable, unsigned char * serialized)`: Serialize the - instance into the serialized buffer. The buffer has to be large enough to - hold the serialized instance. -* `TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)`: - Initialize the instance with the serialized data stored in serialized. - -#### memory management - functions #### - -* `void * TR_malloc(size_t)`: -* `void * TR_calloc(size_t, size_t)`: -* `void * TR_reference(void *)`: -* `size_t TR_getSize(void *)`: -* `void TR_cleanup()`: - -#### memory management - macros #### - -* `TR_MEM_FREE(seg)`: - - -### EXAMPLE ### - -#### optimized memory management #### - -#### create a new class #### - -#### create a new interface #### - -#### implement an interface in a class #### - -#### class extension #### - -TESTING -------- +I would really like to see some people possibly interested in this stuff. +I think it contains some really interesting ideas. -This comes with the start of a unit test suite. -You can use *make test* to build and run the existent tests. +If you like to contribute, contact me via email. You are free to clone +and play with this code. -### REQUIREMENTS +## License -Currently, you need valgrind to build the tests, because some memory checking -is done by the way. +GNU General Public License (Version 3) -CONTRIBUTION ------------- +> 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 . -I would really like to see some people possibly interested in this stuff. -I think it contains some really interesting ideas. +## Author -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. +Georg Hopp <>