diff --git a/src/lib/allocation-cluster.cpp b/src/lib/allocation-cluster.cpp index c7bfcacb2..2ca5d89f8 100644 --- a/src/lib/allocation-cluster.cpp +++ b/src/lib/allocation-cluster.cpp @@ -22,7 +22,10 @@ /** @file allocation-cluster.cpp - ** TODO allocation-cluster.cpp + ** Implementation of [memory management helper functions](\ref allocation-cluster.hpp) + ** for the render engine model. Here, in the actual translation unit, the generic part + ** of these functions is emitted, while the corresponding header provides a strictly + ** typed front-end, based on templates, which forward to the implementation eventually. */ diff --git a/src/lib/bool-checkable.hpp b/src/lib/bool-checkable.hpp index e0bb770ea..529ee521b 100644 --- a/src/lib/bool-checkable.hpp +++ b/src/lib/bool-checkable.hpp @@ -22,7 +22,20 @@ /** @file bool-checkable.hpp - ** TODO bool-checkable.hpp + ** Mix-in for implicit conversion to bool. + ** When inheriting from BoolCheckable, a class becomes convertible + ** to `bool` -- which is implemented by invoking an operation `isValid()` + ** on this class. + ** + ** @deprecated 2016 it is not clear if we'll retain that feature on the long run. + ** Essentially this was needed to work around the dangers of implicit `bool` + ** conversion in C++98, which is largely obsolete since C++11, because the + ** rectified semantics of implicit conversion now prevent most unexpected + ** usages of this conversion function, like e.g. in comparison operators + ** on a derived class. Moreover, fun fact is, the implementation in this + ** header is not even correct, see Ticket #477 + ** On the other hand, the basic idea of exposing a `isValid()` function + ** does not sound too bad... */ diff --git a/src/lib/cmdline.cpp b/src/lib/cmdline.cpp index 38b08dcf5..1d3015fc7 100644 --- a/src/lib/cmdline.cpp +++ b/src/lib/cmdline.cpp @@ -22,7 +22,7 @@ /** @file cmdline.cpp - ** TODO cmdline.cpp + ** Implementation of a wrapper / marker to handle "commandline arguments". */ diff --git a/src/lib/cmdline.hpp b/src/lib/cmdline.hpp index cbd61a807..ec67eef25 100644 --- a/src/lib/cmdline.hpp +++ b/src/lib/cmdline.hpp @@ -22,7 +22,11 @@ /** @file cmdline.hpp - ** TODO cmdline.hpp + ** Class to encapsulate the typical C-style commandline definition. + ** A Cmdline object takes the typical `int argc, int** argv` and _copies_ + ** the referred data into a vector of strings. Thus `Cmdline` is a way to + ** express explicitly on APIs that we are consuming commandline contents, + ** and, moreover, it offers a way more sane interface to deal with those. */ @@ -44,7 +48,7 @@ namespace lib { /** - * Abstraction of the usual "int argc, int** argv"-Commandline, + * Abstraction of the usual `int argc, int** argv`-Commandline, * to be able to treat it as a vector of strings. Inherits from * vector, but provides convenient conversions to * string (joining delimited by space)... diff --git a/src/lib/depend.hpp b/src/lib/depend.hpp index a12c998e5..973a40687 100644 --- a/src/lib/depend.hpp +++ b/src/lib/depend.hpp @@ -42,7 +42,7 @@ This code is heavily inspired by ** functions allows for subclass creation and various other kinds of service management. ** ** - ** \par Why Singletons? Inversion-of-Control and Dependency Injection + ** # Why Singletons? Inversion-of-Control and Dependency Injection ** ** Singletons are frequently over-used, and often they serve as disguised ** global variables to support a procedural programming style. As a remedy, typically @@ -53,19 +53,19 @@ This code is heavily inspired by ** Thus, for Lumiera, the choice to use Singletons was deliberate: we understand the ** Inversion-of-Control principle, yet we want to stay just below the level of building ** a central application manager core. At the usage site, we access a factory for some - ** service by name, where the »name« is actually the type name of an interface - ** or facade. Singleton is used as an implementation of this factory, when the service + ** service *by name*, where the »name« is actually the type name of an interface or + ** facade. Singleton is used as an _implementation_ of this factory, when the service ** is self-contained and can be brought up lazily. ** - ** \par Conventions, Lifecycle and Unit Testing + ** ## Conventions, Lifecycle and Unit Testing ** ** Usually we place an instance of the singleton factory (or some other kind of factory) ** as a static variable within the interface class describing the service or facade. ** As a rule, everything accessible as Singleton is sufficiently self-contained to come - ** up any time -- even prior to \c main(). But at shutdown, any deregistration must be - ** done explicitly using a lifecycle hook. Destructors aren't allowed to do any significant - ** work besides releasing references, and we acknowledge that singletons can be released - ** in \em arbitrary order. + ** up any time -- even prior to `main()`. But at shutdown, any deregistration must be done + ** explicitly using a lifecycle hook. Destructors aren't allowed to do _any significant work_ + ** beyond releasing references, and we acknowledge that singletons can be released + ** in _arbitrary order_. ** ** @see lib::Depend ** @see lib::DependencyFactory @@ -89,6 +89,7 @@ namespace lib { * Access point to singletons and other kinds of dependencies. * Actually this is a Factory object, which is typically placed into a * static field of the Singleton (target) class or some otherwise suitable interface. + * @param SI the class of the Singleton instance * @note uses static fields internally, so all factory configuration is shared per type * @remark there is an ongoing discussion regarding the viability of the * Double Checked Locking pattern, which requires either the context of a clearly defined @@ -98,7 +99,12 @@ namespace lib { * the singleton ctor to be flushed and visible to other threads when releasing the lock? * To my understanding, the answer is yes. See * [POSIX](http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_10) - * @param SI the class of the Singleton instance + * @remark we could consider to rely on a _Meyers Singleton_, where the compiler automatically + * generates the necessary code and guard variable to ensure single-threaded initialisation + * of the instance variable. But the downside of this approach is that we'd loose access + * to the singleton instance variable, which then resides within the scope of a single + * access function. Such would counterfeit the ability to exchange the instance to + * inject a mock for unit testing. */ template class Depend diff --git a/src/lib/dependency-factory.hpp b/src/lib/dependency-factory.hpp index 18b204775..494b1b45a 100644 --- a/src/lib/dependency-factory.hpp +++ b/src/lib/dependency-factory.hpp @@ -22,7 +22,9 @@ /** @file dependency-factory.hpp - ** TODO dependency-factory.hpp + ** Implementation of a singleton factory used to bring up services as dependency. + ** @internal this implementation header belongs to our framework to deal with + ** [service dependencies](\ref depend.hpp) and should not be used directly. */ @@ -45,7 +47,7 @@ namespace lib { /** * @internal Factory to generate and manage service objects classified by type. * An instance of this factory is placed once for each type for use by - * the \c lib::Depend front-end for dependency management. While the latter + * the lib::Depend front-end for dependency management. While the latter * provides the singleton-style initialisation patter, the DependencyFacotry * maintains a customisable factory function for instance creation. Moreover, * the embedded helper template DependencyFactory::InstanceHolder actually diff --git a/src/lib/frameid.hpp b/src/lib/frameid.hpp index 4f2870d8a..40adadfbc 100644 --- a/src/lib/frameid.hpp +++ b/src/lib/frameid.hpp @@ -22,7 +22,14 @@ /** @file frameid.hpp - ** TODO frameid.hpp + ** Marker tuple to identify a specific frame. + ** @todo 2016 the intention was to use this as cache key, and to include + ** some information regarding the processing chain which led up to + ** the calculation of this frame, to allow for intelligent caching + ** and to avoid throwing away most of the frames on each and every + ** tweak of the edit. This marker was added as a preview in 2010 + ** but we didn't get to the point of actually putting that idea + ** into practical use. Yet the basic idea remains desirable... */ diff --git a/src/lib/hash-fnv.c b/src/lib/hash-fnv.c index 9dae835d9..aad48343b 100644 --- a/src/lib/hash-fnv.c +++ b/src/lib/hash-fnv.c @@ -23,7 +23,8 @@ /** @file hash-fnv.c - ** TODO hash-fnv.c + ** Implementation of FNV ("Fowler-Noll-Vo") hashing functions. + ** @remarks code for this implementation is public domain */ diff --git a/src/lib/hash-fnv.h b/src/lib/hash-fnv.h index d8dc5640c..9d1c7a9bb 100644 --- a/src/lib/hash-fnv.h +++ b/src/lib/hash-fnv.h @@ -22,10 +22,9 @@ */ -/** - * @file hash-fnv.h - * Fowler-Noll-Vo Hashes. - * is a non-cryptographic hash function created by Glenn Fowler, Landon Curt Noll, and Phong Vo. +/** @file hash-fnv.h + ** Fowler-Noll-Vo Hashes. + ** FNV is a non-cryptographic hash function created by Glenn Fowler, Landon Curt Noll, and Phong Vo. */ diff --git a/src/lib/lifecycle.cpp b/src/lib/lifecycle.cpp index de73c02df..6b0f003c4 100644 --- a/src/lib/lifecycle.cpp +++ b/src/lib/lifecycle.cpp @@ -22,7 +22,7 @@ /** @file lifecycle.cpp - ** TODO lifecycle.cpp + ** Implementation of installable callbacks for lifecycle events. */ diff --git a/src/lib/lockerror.c b/src/lib/lockerror.c index f78e6af09..39c7430bf 100644 --- a/src/lib/lockerror.c +++ b/src/lib/lockerror.c @@ -22,7 +22,7 @@ /** @file lockerror.c - ** TODO lockerror.c + ** implementation and definitions for error-handling on low-level locking */ diff --git a/src/lib/lockerror.h b/src/lib/lockerror.h index 295a332e9..ba88a3918 100644 --- a/src/lib/lockerror.h +++ b/src/lib/lockerror.h @@ -21,7 +21,7 @@ /** @file lockerror.h - ** TODO lockerror.h + ** definitions and declarations for error-handling on low-level locking */ #ifndef LUMIERA_LOCKERRORS_H diff --git a/src/lib/luid.c b/src/lib/luid.c index a3cc11014..86b965dcf 100644 --- a/src/lib/luid.c +++ b/src/lib/luid.c @@ -22,7 +22,7 @@ /** @file luid.c - ** TODO luid.c + ** Implementation functions for Lumiera's unique object identifier (LUID). */ diff --git a/src/lib/mpool.c b/src/lib/mpool.c index 469305037..9aaa93a01 100644 --- a/src/lib/mpool.c +++ b/src/lib/mpool.c @@ -21,7 +21,7 @@ /** @file mpool.c - ** TODO mpool.c + ** Implementation of pooling memory allocation functions for constant sized objects. */ #include diff --git a/src/lib/mpool.h b/src/lib/mpool.h index bb7ddf184..f4ab30369 100644 --- a/src/lib/mpool.h +++ b/src/lib/mpool.h @@ -21,7 +21,18 @@ /** @file mpool.h - ** TODO mpool.h + ** Pooled memory allocator for constant sized objects + ** *Memory Pools* are implemented as clusters of fixed sized elements. New clusters + ** are allocated on demand or manually preallocated with a mpool_reserve() operation. + ** Some efforts are taken to ensure (cache) locality of the provided memory. + ** All functions are reentrant but not threadsafe, if this is desired it is advised to + ** care for proper locking elsewhere. + ** @warning as of 2016, this is a stalled development effort towards a pooling allocator. + ** An initial working draft was created in 2009, but never challenged by any + ** widespread use beyond some test code. We acknowledge that there _will be_ + ** some kind of optimised allocator -- yet for the time being we rely on + ** several preliminary front-ends, which _could be attached_ to such an + ** allocator eventually, but use plain flat heap allocations right now. */ #include @@ -29,45 +40,19 @@ #include "lib/llist.h" #include "include/logging.h" -/* -//mpool Memory Pools -//mpool ------------ -//mpool -//mpool This memory pools are implemented as clusters of fixed sized elements. New clusters -//mpool are allocated on demand or manually preallocated with a `reserve()` operation. -//mpool Some efforts are taken to ensure (cache) locality of the provided memory. -//mpool All functions are reentrant but not threadsafe, if this is desired it is advised to -//mpool care for proper locking elsewhere. -//mpool -*/ - - -/* -//index.mpool_destroy_fn xref:mpool_destroy_fn[mpool_destroy_fn]:: function prototype for destroying elements -//mpool [[mpool_destroy_fn]] -//mpool .mpool_destroy_fn -//mpool When a memory pool gets destroyed it can call a destructor for any element which is still in the pool. -//mpool This destructor is optional. -//mpool -//mpool typedef void (*mpool_destroy_fn)(void* self) -//mpool -//mpool `self`:: -//mpool element to be destroyed -//mpool -*/ +/** + * Function prototype for destroying elements. + * When a memory pool gets destroyed it can call a destructor for any element which is still in the pool. + * Use of such a destructor is optional. + * @param self element to be destroyed + */ typedef void (*mpool_destroy_fn)(void* self); -/* -//index.struct_mpool xref:struct_mpool[mpool (struct)]:: the memory pool management structure -//mpool [[struct_mpool]] -//mpool .mpool -//mpool typedef struct mpool_struct mpool -//mpool typedef mpool* MPool -//mpool typedef const mpool* const_MPool -//mpool -//mpool This structure should be considered opaque. -*/ +/** + * memory pool management structure. + * This structure should be considered opaque. + */ typedef struct mpool_struct mpool; typedef mpool* MPool; typedef const mpool* const_MPool; @@ -96,81 +81,46 @@ extern void (*mpool_init_hook) (MPool self); /** called before a mpool gets destroyed */ extern void (*mpool_destroy_hook) (MPool self); -/* -//index.mpool_init xref:mpool_init[mpool_init()]:: Initialise a new memory pool -//mpool [[mpool_init]] -//mpool .mpool_init -//mpool Initialise a memory pool, memory pools must be initialised before being used. One can supply -//mpool an optional destructor function for elements, this will be used to destroy elements which are still -//mpool in the pool when it gets destroyed itself. The destructor is _NOT_ called when elements are freed. -//mpool -//mpool MPool mpool_init (MPool self, size_t elem_size, unsigned elements_per_cluster, mpool_move_fn mv, mpool_destroy_fn dtor) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool structure to be initialised -//mpool `elem_size`:: -//mpool size for a single element -//mpool `elements_per_cluster`:: -//mpool how many elements to put into a cluster -//mpool `dtor`:: -//mpool pointer to an optional destructor function or NULL -//mpool return:: -//mpool self -//mpool -*/ +/** + * Initialise a new memory pool. + * Memory pools must be initialised before being used. One can supply + * an optional destructor function for elements, this will be used to destroy elements which are still + * in the pool when it gets destroyed itself. The destructor is _NOT_ called when elements are freed. + * @param self pointer to the memory pool structure to be initialised + * @param elem_size size for a single element + * @param elements_per_cluster how many elements to put into a cluster + * @param dtor pointer to an optional destructor function, may be `NULL` + * @return `self` pointer to the initialised object + */ MPool mpool_init (MPool self, size_t elem_size, unsigned elements_per_cluster, mpool_destroy_fn dtor); -/* -//index.mpool_destroy xref:mpool_destroy[mpool_destroy()]:: destroy a memory pool -//mpool [[mpool_destroy]] -//mpool .mpool_destroy -//mpool A memory pool is not used anymore it should be destroyed. This frees all memory allocated with it. -//mpool When a destructor was provided at construction time, then this destructor is used on all non free elements -//mpool before before the clusters are freed. If no destructor was given then the clusters are just freed. -//mpool The destroyed memory pool behaves as if it was freshly initialised and can be used again, this is some kindof -//mpool exceptional behaviour. -//mpool -//mpool MPool mpool_destroy (MPool self) -//mpool -//mpool `self`:: -//mpool pointer to an initialised memory pool to be destroyed. -//mpool return:: -//mpool self -//mpool -//mpool -*/ +/** + * destroy a memory pool. + * A memory pool not used anymore should be destroyed. This frees all memory allocated with it. + * When a destructor was provided at construction time, then this destructor is used on all non free elements + * before before the clusters are freed. If no destructor was given then the clusters are just freed. + * The destroyed memory pool behaves as if it was freshly initialised and can be used again, this is + * some kind of exceptional behaviour. + * @param self pointer to an initialised memory pool to be destroyed. + * @return `self` + */ MPool mpool_destroy (MPool self); -/* -//index.mpool_purge xref:mpool_purge[mpool_purge()]:: free unused clusters -//mpool [[mpool_purge]] -//mpool .mpool_purge -//mpool -//mpool TODO -//mpool -//mpool -*/ +/** + * free unused clusters. + */ MPool mpool_purge (MPool self); -/* -//index.mpool_available xref:mpool_available[mpool_available()]:: query number of free elements -//mpool [[mpool_available]] -//mpool .mpool_available -//mpool One can check how much elements are available without a new cluster allocation in a memory pool. -//mpool -//mpool unsigned mpool_available (MPool self) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool to be queried -//mpool return:: -//mpool number of available elements -//mpool -*/ +/** + * query number of free elements. + * @param self pointer to the memory pool to be queried + * @return number of elements available in the pool _without allocating a new cluster_ + */ static inline unsigned mpool_available (MPool self) { @@ -178,98 +128,55 @@ mpool_available (MPool self) } -/* -//index.mpool_reserve xref:mpool_reserve[mpool_reserve()]:: preallocate elements -//mpool [[mpool_reserve]] -//mpool .mpool_reserve -//mpool Resize the pool that at least nelements become available without cluster reallocations -//mpool -//mpool unsigned mpool_reserve (MPool self, unsigned nelements) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool `nelements`:: -//mpool minimum number of elements to preallocate -//mpool return:: -//mpool self on success or NULL on error -//mpool -*/ +/** + * preallocate elements. + * Resize the pool that at least the given number of elements are available without cluster reallocations. + * @param self pointer to the memory pool + * @param nelements minimum number of elements to preallocate + * @return self on success or `NULL` on error + */ MPool mpool_reserve (MPool self, unsigned nelements); -/* -//index.mpool_alloc xref:mpool_alloc[mpool_alloc()]:: allocate one element -//mpool [[mpool_alloc]] -//mpool .mpool_alloc -//mpool Allocates on element from a mpool. To improve cache locality allocations -//mpool are grouped close together to recent allocations. -//mpool -//mpool void* mpool_alloc (MPool self) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool return:: -//mpool pointer to the allocated memory on success or NULL on error -//mpool will never fail when enough space was preallocated -//mpool -*/ +/** + * allocate one element from a MPool. To improve cache locality allocations + * are grouped close together to recent allocations. + * @param self pointer to the memory pool + * @return pointer to the allocated memory on success or `NULL` on error + * @note will never fail when enough space was preallocated + */ void* mpool_alloc (MPool self); -/* -//index.mpool_alloc_near xref:mpool_alloc_near[mpool_alloc_near()]:: allocate one element, w/ locality -//mpool [[mpool_alloc_near]] -//mpool .mpool_alloc_near -//mpool Allocates on element from a mpool. To improve cache locality the allocation -//mpool tries to get an element close to another. -//mpool -//mpool void* mpool_alloc_near (MPool self, void* near) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool `near`:: -//mpool reference to another element which should be close to the returned element (hint only) -//mpool return:: -//mpool pointer to the allocated memory on success or NULL on error -//mpool will never fail when enough space was preallocated -//mpool -*/ +/** + * allocate one element close to the given reference element. + * To improve cache locality the allocation tries to get an element close by. + * @param self pointer to the memory pool + * @param near reference to another element which should be close to the returned element _(hint only)_ + * @return pointer to the allocated memory on success or `NULL` on error + * @note will never fail when enough space was preallocated + */ void* mpool_alloc_near (MPool self, void* near); -/* -//index.mpool_free xref:mpool_free[mpool_free()]:: free one element -//mpool [[mpool_free]] -//mpool .mpool_free -//mpool Frees the given element and puts it back into the pool for furhter allocations. -//mpool -//mpool void mpool_free (MPool self, void* element) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool `element`:: -//mpool element to be freed -//mpool -*/ +/** + * free one element. + * Frees the given element and puts it back into the pool for further allocations. + * @param self pointer to the memory pool + * @param element element to be freed + */ void mpool_free (MPool self, void* element); +/** diagnostic dump of MPool allocation */ void nobug_mpool_dump (const_MPool self, const int depth, const struct nobug_context dump_context, void* extra); - -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ diff --git a/src/lib/mrucache.c b/src/lib/mrucache.c index 7eacc8339..cfcc2d25e 100644 --- a/src/lib/mrucache.c +++ b/src/lib/mrucache.c @@ -21,7 +21,7 @@ /** @file mrucache.c - ** TODO mrucache.c + ** Implementation of a caching by most recent use. */ #include "lib/safeclib.h" diff --git a/src/lib/mrucache.h b/src/lib/mrucache.h index eeb871981..e2ae8c03d 100644 --- a/src/lib/mrucache.h +++ b/src/lib/mrucache.h @@ -19,20 +19,22 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -#ifndef LUMIERA_CACHE_H -#define LUMIERA_CACHE_H + +/** @file mrucache.h + ** Most recent used cache. + ** Elements (addressed by a LList node) are either checked in the cache and thereby subject of aging + ** or checked out under control of the user. Most operations require that the cache is locked. + ** @warning not threadsafe. Locking must be done from usage site. + */ + + +#ifndef LIB_MRUCACHE_H +#define LIB_MRUCACHE_H #include "lib/llist.h" #include -/** - * @file - * Most recent used cache - * Elements (addressed by a LList node) are either checked in the cache and thereby subject of aging - * or checked out under control of the user. Most operations require that the cache is locked. This locking - * must be done from elsewhere. - */ /** * Callback function used to destroy/cleanup aged elements. @@ -176,4 +178,4 @@ int lumiera_mrucache_age (LumieraMruCache self, int nelem); -#endif +#endif /*LIB_MRUCACHE_H*/ diff --git a/src/lib/nobug-init.cpp b/src/lib/nobug-init.cpp index ca13baad0..0c222275b 100644 --- a/src/lib/nobug-init.cpp +++ b/src/lib/nobug-init.cpp @@ -22,11 +22,12 @@ /** @file nobug-init.cpp - ** TODO nobug-init.cpp + ** Implementation function for automatic trigger of NoBug initialisation + ** @note `#include` nobug-init.hpp to use this initialisation automatically */ -#include "lib/nobug-init.hpp" +#include /// magic to generate NoBug logging definitions #define LUMIERA_NOBUG_INIT_CPP diff --git a/src/lib/nocopy.hpp b/src/lib/nocopy.hpp index 6fd3db8a7..e916306a3 100644 --- a/src/lib/nocopy.hpp +++ b/src/lib/nocopy.hpp @@ -22,7 +22,10 @@ /** @file nocopy.hpp - ** TODO nocopy.hpp + ** Mix-Ins to allow or prohibit various degrees of copying and cloning. + ** @todo 2016 this could be organised way better. Also C++11 offers a way more + ** elegant way of expressing the intention. We could get rid of `boost::noncopyable` + ** The basic idea of using a marker mixin seems very reasonable though. ////////////////////////////TICKET #1084 */ diff --git a/src/lib/optional-ref.hpp b/src/lib/optional-ref.hpp index 4baad2112..ee32ea0e2 100644 --- a/src/lib/optional-ref.hpp +++ b/src/lib/optional-ref.hpp @@ -22,7 +22,9 @@ /** @file optional-ref.hpp - ** TODO optional-ref.hpp + ** a checked, switchable reference. + ** Offers semantics similar to a pointer, but throws (not segfaults) + ** on invalid dereferentiation */ diff --git a/src/lib/priqueue.c b/src/lib/priqueue.c index 10b79d6bc..e32da1d84 100644 --- a/src/lib/priqueue.c +++ b/src/lib/priqueue.c @@ -22,7 +22,7 @@ /** @file priqueue.c - ** TODO priqueue.c + ** a simple "text book" implementation of a priority queue, based on a binary heap */ diff --git a/src/lib/psplay.c b/src/lib/psplay.c index ae154a232..478441f60 100644 --- a/src/lib/psplay.c +++ b/src/lib/psplay.c @@ -23,7 +23,7 @@ /** @file psplay.c - ** TODO psplay.c + ** Probabilistic splay tree implementation */ #include "include/logging.h" diff --git a/src/lib/psplay.h b/src/lib/psplay.h index f88ac8cb5..5bad01128 100644 --- a/src/lib/psplay.h +++ b/src/lib/psplay.h @@ -21,23 +21,25 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -#ifndef PSPLAY_H -#define PSPLAY_H + +/** @file psplay.h + ** Probabilistic splay tree. + ** A splay trees is self-optimising (in contrast to self-balancing) datastructure. + ** We introduce here a probabilistic bottom up approach which reduces the splay costs. + ** Without affecting the performance. The randomisation gives also some insurance that + ** worst case situations are extremely unlikely. + ** + ** Tree nodes are very small (just 2 pointers) and are intrusively placed into the users + ** datastructure. + */ + + +#ifndef LIB_PSPLAY_H +#define LIB_PSPLAY_H #include #include -/** - * @file - * Probabilistic splay trees - * A splay trees is self-optimizing (in contrast to self-balancing) datastructure. - * We introduce here a probabilistic bottom up approach which reduces the splay costs. - * Without affecting the performance. The randomization gives also some insurance that - * worst case situations are extremely unlikely. - * Tree nodes are very small (just 2 pointers) and are intrusively placed into the users - * datastructure. - */ - /** * Type and handle for a psplay tree node @@ -283,11 +285,4 @@ psplay_walk (PSplay self, PSplaynode node, psplay_action_fn action, int level, v void psplay_dump (PSplay self, FILE* dest); -#endif -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ +#endif /*LIB_PSPLAY_H*/ diff --git a/src/lib/query-diagnostics.hpp b/src/lib/query-diagnostics.hpp index 5bae2f35a..f7283fe37 100644 --- a/src/lib/query-diagnostics.hpp +++ b/src/lib/query-diagnostics.hpp @@ -22,7 +22,7 @@ /** @file query-diagnostics.hpp - ** TODO query-diagnostics.hpp + ** diagnostic helpers to support test related to predicate queries */ diff --git a/src/lib/query-text.cpp b/src/lib/query-text.cpp index d09ba8bb9..6a3f152db 100644 --- a/src/lib/query-text.cpp +++ b/src/lib/query-text.cpp @@ -22,32 +22,20 @@ /** @file query-text.cpp - ** TODO query-text.cpp + ** Implementation bits regarding a syntactical standard representation of predicate queries */ -//#include "lib/util.hpp" -//#include "lib/symbol.hpp" -//#include "include/logging.h" #include "lib/query-text.hpp" -//#include #include #include -//#include -//using std::map; using std::string; -//using util::contains; -//using util::isnil; namespace lib { - namespace { // internal details - - } // internal details - /** Parse, verify and normalise the raw query definition * @warning right now (2012) we don't normalise at all diff --git a/src/lib/query-util.cpp b/src/lib/query-util.cpp index d91c99d89..b370018d9 100644 --- a/src/lib/query-util.cpp +++ b/src/lib/query-util.cpp @@ -22,7 +22,7 @@ /** @file query-util.cpp - ** TODO query-util.cpp + ** Implementation of helpers for working with predicate queries. */ diff --git a/src/lib/query-util.hpp b/src/lib/query-util.hpp index f604d3904..a76f4a6ca 100644 --- a/src/lib/query-util.hpp +++ b/src/lib/query-util.hpp @@ -22,7 +22,7 @@ /** @file query-util.hpp - ** TODO query-util.hpp + ** Utilities to support working with predicate queries */ diff --git a/src/lib/ref-array.hpp b/src/lib/ref-array.hpp index 7f79fb40f..22545c792 100644 --- a/src/lib/ref-array.hpp +++ b/src/lib/ref-array.hpp @@ -22,7 +22,9 @@ /** @file ref-array.hpp - ** TODO ref-array.hpp + ** Abstraction interface: array-like access by subscript + ** @todo as of 2016, this concept seems very questionable: do we _really_ want + ** to abstract over random access, or do we _actually_ want for-iteration?? */ @@ -42,12 +44,14 @@ namespace lib { * holding subclasses. */ template - struct RefArray : boost::noncopyable + class RefArray + : boost::noncopyable { + public: + virtual ~RefArray() {} ///< this is an interface + virtual T const& operator[] (size_t i) const =0; virtual size_t size() const =0; - - virtual ~RefArray() {} }; diff --git a/src/lib/safeclib.c b/src/lib/safeclib.c index 8dc295956..72fb9688a 100644 --- a/src/lib/safeclib.c +++ b/src/lib/safeclib.c @@ -17,12 +17,15 @@ You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -*/ + +* *****************************************************/ /** @file safeclib.c - ** TODO safeclib.c + ** Implementation of error-safe wrappers for some notorious C-Lib functions. */ + + #include "lib/error.h" #include "lib/safeclib.h" diff --git a/src/lib/safeclib.h b/src/lib/safeclib.h index c1fe79554..2a6ab5fb0 100644 --- a/src/lib/safeclib.h +++ b/src/lib/safeclib.h @@ -1,5 +1,5 @@ /* - safe_clib.h - Portable and safe wrappers around some clib functions and some tools + SAFECLIB.h - Portable and safe wrappers around some clib functions and some tools Copyright (C) CinelerraCV 2008, Christian Thaeter @@ -19,14 +19,16 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file safeclib.h + ** Portable and safe wrappers around some C-Lib functions + */ + + #include "error.h" #include -/** - * @file - * Portable and safe wrappers around some clib functions and some tools - */ LUMIERA_ERROR_DECLARE(NO_MEMORY); /** diff --git a/src/lib/scoped-holder-transfer.hpp b/src/lib/scoped-holder-transfer.hpp index a8b36401d..f6f6df242 100644 --- a/src/lib/scoped-holder-transfer.hpp +++ b/src/lib/scoped-holder-transfer.hpp @@ -22,7 +22,9 @@ /** @file scoped-holder-transfer.hpp - ** TODO scoped-holder-transfer.hpp + ** A mechanism to take ownership without allowing copy. + ** @deprecated obsolete concept, superseded by C++11 rvalue references + ** @todo expunge this! */ diff --git a/src/lib/searchpath.cpp b/src/lib/searchpath.cpp index 2f67f6e7e..4ff7be21f 100644 --- a/src/lib/searchpath.cpp +++ b/src/lib/searchpath.cpp @@ -22,7 +22,7 @@ /** @file searchpath.cpp - ** TODO searchpath.cpp + ** Implementation of helpers to handle directory search paths. */ diff --git a/src/lib/searchpath.hpp b/src/lib/searchpath.hpp index 3de3c6c92..88a3f0c5b 100644 --- a/src/lib/searchpath.hpp +++ b/src/lib/searchpath.hpp @@ -22,7 +22,11 @@ /** @file searchpath.hpp - ** TODO searchpath.hpp + ** Helpers to handle directory search paths. + ** The SerachPathSplitter allows to evaluate a "path" like specification + ** with colon separated components. It is complemented by some magic convenience + ** functions to self-discover the currently running executable and to resolve + ** the `$ORIGIN` pattern similar to what is known from linker `rpath` / `runpath` */ diff --git a/src/lib/sectionlock.h b/src/lib/sectionlock.h index 28245029d..1e2f3e056 100644 --- a/src/lib/sectionlock.h +++ b/src/lib/sectionlock.h @@ -21,7 +21,7 @@ /** @file sectionlock.h - ** TODO sectionlock.h + ** Mutex state handle for locked code sections */ #ifndef LUMIERA_SECTIONLOCK_H diff --git a/src/lib/tmpbuf.c b/src/lib/tmpbuf.c index 59bb180f6..f5993b959 100644 --- a/src/lib/tmpbuf.c +++ b/src/lib/tmpbuf.c @@ -1,5 +1,5 @@ /* - tmpbuf.c - Round Robin Temporary buffers + Tmpbuf - Round Robin Temporary buffers Copyright (C) Lumiera.org 2008, 2010 Christian Thaeter @@ -17,12 +17,18 @@ You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -*/ + +* *****************************************************/ /** @file tmpbuf.c - ** TODO tmpbuf.c + ** Implementation of temporary buffers with round-robin usage pattern. + ** + ** @warning this is the restored old version from bc989dab7a97fc69c (July 2010) + ** (the improved version is still buggy as of 5/2011) */ + + #include "lib/safeclib.h" #include "lib/tmpbuf.h" @@ -34,11 +40,6 @@ #include -/*!! WARNING - *!! - *!! this is the restored old version from bc989dab7a97fc69c (July 2010) - *!! (the improved version is still buggy as of 5/2011) - */ struct lumiera_tmpbuf_struct { diff --git a/src/lib/tmpbuf.h b/src/lib/tmpbuf.h index 76b3ceaec..f67c7ef62 100644 --- a/src/lib/tmpbuf.h +++ b/src/lib/tmpbuf.h @@ -1,5 +1,5 @@ /* - tmpbuf.c - Round Robin Temporary buffers + TMPBUF.h - Round Robin Temporary buffers Copyright (C) Lumiera.org 2008, 2010 Christian Thaeter @@ -17,29 +17,37 @@ You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + */ + +/** @file tmpbuf.h + ** Round robin temporary buffers. + ** This helper provides some buffers per thread which are round-robin recycled with each use. + ** The idea is to have fast buffers for temporal data without need for explicit heap management. + ** There is a fixed number of buffers per thread, which will be re-used with a round-robin pattern, + ** without any safety checks. The caller just needs to ensure not to use too much of these buffers. + ** Typical usage is for "just printing a damn number", hand it over to a library, which will copy + ** the data anyway. + ** + ** @warning this is the restored old version from bc989dab7a97fc69c (July 2010) + ** (the improved version is still buggy as of 5/2011) + */ + + #ifndef LUMIERA_TMPBUF_H #define LUMIERA_TMPBUF_H #include -/** - * @file - * Round robin temporary buffers. - * This provides some buffers per thread which are round-robin recycled with each use. - * The idea is to have fast buffers for temporal data without need for explicit heap management. - * - * @warning this is the restored old version from bc989dab7a97fc69c (July 2010) - * (the improved version is still buggy as of 5/2011) - */ -/* following value must be exponent of 2 */ /** * Number of buffers in the ring * This also defines how many concurent buffers can be in use in one thread (including nested calls) * tmpbufs are only suitable for nested calls where one knows in advance how much tmpbufs might be used + * + * @warning the value defined here must be a power of 2 */ #define LUMIERA_TMPBUF_NUM 16 diff --git a/src/lib/util-quant.hpp b/src/lib/util-quant.hpp index c0d4bd30b..063ee430b 100644 --- a/src/lib/util-quant.hpp +++ b/src/lib/util-quant.hpp @@ -22,7 +22,7 @@ /** @file util-quant.hpp - ** TODO util-quant.hpp + ** Utilities for quantisation (grid alignment) and comparisons. */ diff --git a/src/lib/util.cpp b/src/lib/util.cpp index 0eeb3c174..7ab8dfe67 100644 --- a/src/lib/util.cpp +++ b/src/lib/util.cpp @@ -22,7 +22,10 @@ /** @file util.cpp - ** TODO util.cpp + ** Implementation of widely used helper functions. + ** The helpers implemented here are typically accessed by including util.hpp, + ** so the reason of pushing down the implementation into a separate translation unit + ** (this one here) is to avoid more heavyweight includes (e.g. boost). */ diff --git a/src/lib/util.hpp b/src/lib/util.hpp index 4e00fc7ae..c3a3e6291 100644 --- a/src/lib/util.hpp +++ b/src/lib/util.hpp @@ -22,7 +22,15 @@ /** @file util.hpp - ** TODO util.hpp + ** Tiny helper functions and shortcuts to be used _everywhere_ + ** Consider this header to be effectively included in almost every translation unit. + ** @remark The motivation of using these helpers is conciseness and uniformity of expression. + ** There are several extensions and not-so-frequently used supplements packaged into + ** separate headers. + ** @warning be sure to understand the ramifications of including _anything_ here... + ** @see util-coll.hpp + ** @see uitl-foreach.hpp + ** @see util-quant.hpp */ diff --git a/src/lib/visitor-dispatcher.hpp b/src/lib/visitor-dispatcher.hpp index 60dbc78e5..034d25b9e 100644 --- a/src/lib/visitor-dispatcher.hpp +++ b/src/lib/visitor-dispatcher.hpp @@ -22,7 +22,8 @@ /** @file visitor-dispatcher.hpp - ** TODO visitor-dispatcher.hpp + ** Helper for a trampoline table based implementation of the visitor pattern. + ** @internal implementation part, clients should include visitor.hpp */ diff --git a/src/lib/visitor.hpp b/src/lib/visitor.hpp index 08b3a8abc..f15eae4b0 100644 --- a/src/lib/visitor.hpp +++ b/src/lib/visitor.hpp @@ -36,8 +36,8 @@ Credits for many further implementation ideas go to /** @file visitor.hpp - ** A library implementation of the Visitor Pattern tailored specifically - ** to Lumiera's needs within the Proc Layer. Visitor enables double dispatch + ** A library implementation of the *Visitor Pattern* tailored specifically + ** to Lumiera's needs within the Proc Layer. Visitor enables *double dispatch* ** calls, based both on the concrete type of some target object and the concrete type of ** a tool object being applied to this target. The code carrying out this tool application ** (and thus triggering the double dispatch) need not know any of these concrete types and is @@ -47,22 +47,27 @@ Credits for many further implementation ideas go to ** concrete target visitable type. ** ** Implementation notes - **
  • driven by dispatch tables with trampoline functions.
    • - **
  • uses Typelists and Template metaprogramming to generate - ** Dispatcher tables for the concrete types.
    • - **
  • individual Visiting Tool implementation classes need to derive - ** from some Applicable > instantiation - ** and thus define which calls they get dispatched. This is \b crucial. - ** A concrete type not declared in this way will never be dispatched to this - ** concrete visiting tool implementation class. Of course, the latter is free - ** to implement corresponding "treat(ConcreteVisitable&) functions or fall back - ** on some treat(VisitableInterface&) function.
    • - **
  • any concrete Visitable subclass wanting to be treated by some concrete tool - ** needs to use the DECLARE_PROCESSABLE_BY(TOOLBASE) macro. By this, it gets an - ** virtual `apply(TOOLBASE&)` function. Otherwise, it will be treated by the - ** interface of the next base class using this macro.
    • - **
- ** For design questions and more detailed implementation notes, see the Proc Layer Tiddly Wiki. + ** - driven by dispatch tables with trampoline functions. + ** - uses Typelists and Template metaprogramming to generate + ** Dispatcher tables for the concrete types. + ** - individual Visiting Tool implementation classes need to derive + ** from some Applicable > instantiation + ** and thus define which calls they get dispatched. _This is crucial_. + ** A concrete type not declared in this way will never be dispatched to this + ** concrete visiting tool implementation class. Of course, the latter is free + ** to implement corresponding "treat(ConcreteVisitable&) functions or fall back + ** on some treat(VisitableInterface&) function. + ** - any concrete Visitable subclass wanting to be treated by some concrete tool + ** needs to use the `DECLARE_PROCESSABLE_BY(TOOLBASE)` macro. By this, it gets an + ** virtual `apply(TOOLBASE&)` function. Otherwise, it will be treated by the + ** interface of the next base class using this macro. + ** + ** @remarks as of 2016, it is not clear if we'll really use this facility; it was meant to play a + ** crucial role in the Builder (which is not implemented yet....). The fundamental idea of relying + ** on a visitor seems still adequate though. For design questions and more detailed implementation + ** notes, see the [TiddlyWiki]. + ** + ** [TiddlyWiki]: http://lumiera.org/wiki/renderengine.html#VisitorUse%20VisitingToolImpl%20BuilderStructures%20BuilderMechanics "Lumiera Tiddly Wiki" ** ** @see visitingtooltest.cpp test cases using our lib implementation ** @see BuilderTool one especially important instantiation diff --git a/src/lib/wrapperptr.hpp b/src/lib/wrapperptr.hpp index 5fb91a003..6c3dfb224 100644 --- a/src/lib/wrapperptr.hpp +++ b/src/lib/wrapperptr.hpp @@ -22,7 +22,8 @@ /** @file wrapperptr.hpp - ** TODO wrapperptr.hpp + ** Wrapper to treat several flavours of smart-pointers uniformly + ** @deprecated as of 2016 we should re-think how to organise visitor use in the Builder */ diff --git a/src/lumiera/main.cpp b/src/lumiera/main.cpp index d74359cbd..817f6dfb1 100644 --- a/src/lumiera/main.cpp +++ b/src/lumiera/main.cpp @@ -23,7 +23,7 @@ /** @file main.cpp - ** TODO main.cpp + ** Lumiera application main function */