Doxygen: fill in missing file level headlines for the Library
This commit is contained in:
parent
545a07db33
commit
8e6936d0ad
43 changed files with 287 additions and 312 deletions
|
|
@ -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.
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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...
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file cmdline.cpp
|
||||
** TODO cmdline.cpp
|
||||
** Implementation of a wrapper / marker to handle "commandline arguments".
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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<std::string>, but provides convenient conversions to
|
||||
* string (joining delimited by space)...
|
||||
|
|
|
|||
|
|
@ -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 <i>by name</i>, 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 SI>
|
||||
class Depend
|
||||
|
|
|
|||
|
|
@ -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 <i>once for each type</i> for use by
|
||||
* the \c lib::Depend<TY> front-end for dependency management. While the latter
|
||||
* the lib::Depend<TY> 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
|
||||
|
|
|
|||
|
|
@ -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...
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file lifecycle.cpp
|
||||
** TODO lifecycle.cpp
|
||||
** Implementation of installable callbacks for lifecycle events.
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file lockerror.c
|
||||
** TODO lockerror.c
|
||||
** implementation and definitions for error-handling on low-level locking
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@
|
|||
|
||||
|
||||
/** @file lockerror.h
|
||||
** TODO lockerror.h
|
||||
** definitions and declarations for error-handling on low-level locking
|
||||
*/
|
||||
|
||||
#ifndef LUMIERA_LOCKERRORS_H
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file luid.c
|
||||
** TODO luid.c
|
||||
** Implementation functions for Lumiera's unique object identifier (LUID).
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@
|
|||
|
||||
|
||||
/** @file mpool.c
|
||||
** TODO mpool.c
|
||||
** Implementation of pooling memory allocation functions for constant sized objects.
|
||||
*/
|
||||
|
||||
#include <stdlib.h>
|
||||
|
|
|
|||
253
src/lib/mpool.h
253
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 <stdint.h>
|
||||
|
|
@ -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:
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@
|
|||
|
||||
|
||||
/** @file mrucache.c
|
||||
** TODO mrucache.c
|
||||
** Implementation of a caching by most recent use.
|
||||
*/
|
||||
|
||||
#include "lib/safeclib.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 <nobug.h>
|
||||
|
||||
/**
|
||||
* @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*/
|
||||
|
|
|
|||
|
|
@ -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 <nobug.h>
|
||||
|
||||
/// magic to generate NoBug logging definitions
|
||||
#define LUMIERA_NOBUG_INIT_CPP
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file priqueue.c
|
||||
** TODO priqueue.c
|
||||
** a simple "text book" implementation of a priority queue, based on a binary heap
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@
|
|||
|
||||
|
||||
/** @file psplay.c
|
||||
** TODO psplay.c
|
||||
** Probabilistic splay tree implementation
|
||||
*/
|
||||
|
||||
#include "include/logging.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 <stdint.h>
|
||||
#include <stdio.h>
|
||||
|
||||
/**
|
||||
* @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*/
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file query-diagnostics.hpp
|
||||
** TODO query-diagnostics.hpp
|
||||
** diagnostic helpers to support test related to predicate queries
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <boost/noncopyable.hpp>
|
||||
#include <boost/functional/hash.hpp>
|
||||
#include <string>
|
||||
//#include <map>
|
||||
|
||||
//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
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file query-util.cpp
|
||||
** TODO query-util.cpp
|
||||
** Implementation of helpers for working with predicate queries.
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file query-util.hpp
|
||||
** TODO query-util.hpp
|
||||
** Utilities to support working with predicate queries
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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<class T>
|
||||
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() {}
|
||||
};
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <ct@pipapo.org>
|
||||
|
|
@ -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 <stdlib.h>
|
||||
|
||||
/**
|
||||
* @file
|
||||
* Portable and safe wrappers around some clib functions and some tools
|
||||
*/
|
||||
LUMIERA_ERROR_DECLARE(NO_MEMORY);
|
||||
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file searchpath.cpp
|
||||
** TODO searchpath.cpp
|
||||
** Implementation of helpers to handle directory search paths.
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@
|
|||
|
||||
|
||||
/** @file sectionlock.h
|
||||
** TODO sectionlock.h
|
||||
** Mutex state handle for locked code sections
|
||||
*/
|
||||
|
||||
#ifndef LUMIERA_SECTIONLOCK_H
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
tmpbuf.c - Round Robin Temporary buffers
|
||||
Tmpbuf - Round Robin Temporary buffers
|
||||
|
||||
Copyright (C) Lumiera.org
|
||||
2008, 2010 Christian Thaeter <ct@pipapo.org>
|
||||
|
|
@ -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 <nobug.h>
|
||||
|
||||
|
||||
/*!! 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
|
||||
{
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
tmpbuf.c - Round Robin Temporary buffers
|
||||
TMPBUF.h - Round Robin Temporary buffers
|
||||
|
||||
Copyright (C) Lumiera.org
|
||||
2008, 2010 Christian Thaeter <ct@pipapo.org>
|
||||
|
|
@ -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 <stdlib.h>
|
||||
|
||||
/**
|
||||
* @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
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@
|
|||
|
||||
|
||||
/** @file util-quant.hpp
|
||||
** TODO util-quant.hpp
|
||||
** Utilities for quantisation (grid alignment) and comparisons.
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -36,8 +36,8 @@ Credits for many further implementation ideas go to
|
|||
|
||||
|
||||
/** @file visitor.hpp
|
||||
** A library implementation of the <b>Visitor Pattern</b> tailored specifically
|
||||
** to Lumiera's needs within the Proc Layer. Visitor enables <b>double dispatch</b>
|
||||
** 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
|
||||
** <ul><li>driven by dispatch tables with trampoline functions.</li>
|
||||
** <li>uses Typelists and Template metaprogramming to generate
|
||||
** Dispatcher tables for the concrete types.</li>
|
||||
** <li>individual Visiting Tool implementation classes need to derive
|
||||
** from some Applicable<TOOLImpl, Types<Type1,Type2,...> > 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.</li>
|
||||
** <li>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.</li>
|
||||
** </ul>
|
||||
** 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<TOOLImpl, Types<Type1,Type2,...> > 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@
|
|||
|
||||
|
||||
/** @file main.cpp
|
||||
** TODO main.cpp
|
||||
** Lumiera application main function
|
||||
*/
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue