From 41ad41d1f10b3df09bcd5ad981f70a59092a89c4 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Wed, 15 Oct 2014 23:08:53 +0200 Subject: [PATCH] clean-up: sourcefile layout and spell checking Uniform sequence at start of source files - copyright claim - license - file comment - header guard - lumiera includes - library / system includes Lumiera uses Brittish spelling. Add an according note to the styleguide. --- doc/devel/rfc/CodingStyle.txt | 19 ++- doc/technical/code/codingGuidelines.txt | 11 +- src/backend/backend.c | 9 +- src/backend/backend.h | 13 +- src/backend/engine/job.h | 10 +- src/backend/file-handling.c | 2 +- src/backend/file.h | 71 +++++----- src/backend/filedescriptor.c | 10 +- src/backend/filedescriptor.h | 31 ++--- src/backend/filedescriptorregistry.c | 17 +-- src/backend/filedescriptorregistry.h | 31 +++-- src/backend/filehandle.c | 10 +- src/backend/filehandle.h | 40 +++--- src/backend/filehandlecache.c | 13 +- src/backend/filehandlecache.h | 35 ++--- src/backend/fileheader.c | 20 ++- src/backend/fileheader.h | 69 +++++----- src/backend/mmap.c | 44 +++---- src/backend/mmap.h | 44 ++++--- src/backend/mmapcache.c | 18 ++- src/backend/mmapcache.h | 35 ++--- src/backend/mmapings.c | 13 +- src/backend/mmapings.h | 49 +++---- src/backend/resourcecollector.c | 11 +- src/backend/resourcecollector.h | 29 ++-- src/backend/threadpool.c | 27 ++-- src/backend/threadpool.h | 28 ++-- src/backend/threads.c | 64 ++++----- src/backend/threads.h | 88 ++++++------- src/common/config-interface.c | 17 +-- src/common/config-interface.h | 20 ++- src/common/config-lookup.c | 26 ++-- src/common/config-lookup.h | 53 ++++---- src/common/config-typed.c | 33 +++-- src/common/config-wordlist.c | 6 +- src/common/config.c | 29 ++-- src/common/config.h | 69 +++++----- src/common/configentry.c | 26 +--- src/common/configentry.h | 28 ++-- src/common/configitem.c | 22 ++-- src/common/configitem.h | 97 ++++++-------- src/common/interface-descriptor.h | 13 +- src/common/interface.c | 33 +++-- src/common/interface.h | 146 ++++++++++----------- src/common/interfaceregistry.c | 25 ++-- src/common/interfaceregistry.h | 31 ++--- src/common/plugin-dynlib.c | 14 +- src/common/plugin.c | 9 +- src/common/plugin.h | 97 +++++++------- src/lib/condition.h | 2 +- src/lib/cuckoo.h | 16 +-- src/lib/llist.h | 10 +- src/lib/luid.h | 4 +- src/lib/mpool.c | 4 +- src/lib/mpool.h | 14 +- src/lib/mrucache.h | 10 +- src/lib/mutex.h | 6 +- src/lib/psplay.h | 8 +- src/lib/reccondition.h | 4 +- src/lib/recmutex.h | 6 +- src/lib/rwlock.h | 4 +- src/lib/safeclib.h | 6 +- src/lib/slist.h | 14 +- src/tool/alsa.c | 8 +- tests/15mpool.tests | 2 +- tests/20config_lowlevel.tests | 4 +- tests/30mmap.tests | 2 +- tests/core/application/test-configloader.c | 2 +- tests/library/c-lib/test-mpool.c | 20 +-- 69 files changed, 853 insertions(+), 948 deletions(-) diff --git a/doc/devel/rfc/CodingStyle.txt b/doc/devel/rfc/CodingStyle.txt index 64afac562..73d79ba94 100644 --- a/doc/devel/rfc/CodingStyle.txt +++ b/doc/devel/rfc/CodingStyle.txt @@ -20,7 +20,7 @@ Define coding style standard which we will use. Description ~~~~~~~~~~~ -We need to agree on some coding style, imo constistency is the most important +We need to agree on some coding style, IMHO consistency is the most important part with this, no matter which style we use. See http://en.wikipedia.org/wiki/Indent_style[] @@ -29,19 +29,18 @@ See http://en.wikipedia.org/wiki/Indent_style[] * no tabs, use spaces! .Proposed: -* K&R by ichthyo +* K&R by _ichthyo_ * compact and well known -* GNU by cehteh +* GNU by _cehteh_ * imo the best readability (albeit little strange) -* cinelerra might apply as official GNU project someday +* Lumiera might apply as official GNU project someday Another question: __how to write identifiers?__ .Proposed: -* ichthyo: use link:CamelCase[], start ClassNames upper case and variableNames - in lower case. Make all namespaces and package (dir) names completely - lowercase +* ichthyo: use CamelCase, start ClassNames upper case and variableNames + in lower case. Make all namespaces and package (dir) names completely lowercase @@ -76,11 +75,11 @@ MichaelPloujnikov:: '2007-06-27 17:17' I just proposed K&R because it is widely accepted. Personally, I was never very -fond of K&R style, I always prefered putting opening braces to the left. I -never used GNU style until now, but it looks somewhat apealing to me. (btw, +fond of K&R style, I always preferred putting opening braces to the left. I +never used GNU style until now, but it looks somewhat appealing to me. (btw, ECLIPSE comes with presets for all this styles :-P ). Anyhow, I can adapt to most any style. The only thing I really dislike is using tabs (with the -exeption of database DDLs and CSound files, where tab are actually helpful) :) +exception of database DDLs and CSound files, where tab are actually helpful) :) Ichthyo:: '2007-06-27 20:55' diff --git a/doc/technical/code/codingGuidelines.txt b/doc/technical/code/codingGuidelines.txt index 1a0aeb89e..33730a3d8 100644 --- a/doc/technical/code/codingGuidelines.txt +++ b/doc/technical/code/codingGuidelines.txt @@ -11,7 +11,7 @@ The Lumiera project uses GNU indentation style with slight adaptations. - *no tabs* please. The typical ``semi indent'' of GNU style thus becomes 2 spaces. - maximum line length is rather around *110 characters*. -- originally, GNU style focussed on plain-C code. + +- originally, GNU style focused on plain-C code. + We thus apply some relaxations and clarifications ... * the braces for a class scope are indented by 2 spaces @@ -46,7 +46,7 @@ and that library or language uses other conventions. - type names start with an uppercase letter - variable and function names start with lowercase. - fields within a class, especially the private ones are decorated with a trailing underscore -- a leading underscore may be used to emphasize the strictly internal or technical nature of a type, +- a leading underscore may be used to emphasise the strictly internal or technical nature of a type, variable or function - namespaces are all-lowercase - macros and constants are preferably all-caps (at least where this makes sense) @@ -69,6 +69,11 @@ In case a definition actually denotes an object, there should be The object pointer/handle should be passed as 1^st^ argument with the name +self+ +Spelling +~~~~~~~~ +Lumiera uses _British spelling._ Please set your spell checker accordingly. + + General Code Arrangement and Layout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Headers and translation units are named `*.hpp` and `*.cpp` rsp. `*.h` and `*.c` + @@ -77,7 +82,7 @@ General Code Arrangement and Layout the +CamelCaseWords+ of this type are translated into +camel-case-words.hpp+ - Each file should start with the GNU licence preamble. The headline should give a one-line summary. The primary author(s) and the year of the initial copyright claim should be mentioned. -- Each header should be focussed on a specific purpose. Preferably it starts with a file-level +- Each header should be focused on a specific purpose. Preferably it starts with a file-level doxygen comment explaining the intention and anything not obvious from reading the code. - when arranging headers and compilation units, please take care of the compilation times and the code size. Avoid unnecessary includes. Use forward declarations where applicable. diff --git a/src/backend/backend.c b/src/backend/backend.c index 94124c653..87b8ee42d 100644 --- a/src/backend/backend.c +++ b/src/backend/backend.c @@ -1,5 +1,5 @@ /* - backend - common lumiera backend things + Backend - common lumiera backend facilities Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/safeclib.h" @@ -84,7 +86,7 @@ lumiera_backend_init (void) const char* filehandles = lumiera_tmpbuf_snprintf (SIZE_MAX, "backend.file.max_handles = %d", - /* roughly 2/3 of all availables filehandles are managed by the backend */ + /* roughly 2/3 of all available filehandles are managed by the backend */ (sysconf (_SC_OPEN_MAX)-10)*2/3); lumiera_config_setdefault (filehandles); @@ -117,6 +119,7 @@ lumiera_backend_init (void) return 0; } + void lumiera_backend_destroy (void) { diff --git a/src/backend/backend.h b/src/backend/backend.h index 163c8fc7c..e8b5f7b7b 100644 --- a/src/backend/backend.h +++ b/src/backend/backend.h @@ -1,5 +1,5 @@ /* - backend - common lumiera backend things + BACKEND.h - common lumiera backend definitions Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,15 +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. + */ -#ifndef LUMIERA_BACKEND_H -#define LUMIERA_BACKEND_H + + +#ifndef BACKEND_BACKEND_H +#define BACKEND_BACKEND_H #include "lib/mutex.h" #include -//NOBUG_DECLARE_FLAG (backend); + extern size_t lumiera_backend_pagesize; @@ -43,4 +46,4 @@ lumiera_backend_init (void); void lumiera_backend_destroy (void); -#endif +#endif /*BACKEND_BACKEND_H*/ diff --git a/src/backend/engine/job.h b/src/backend/engine/job.h index fb27e63d3..43b6d57d2 100644 --- a/src/backend/engine/job.h +++ b/src/backend/engine/job.h @@ -95,12 +95,12 @@ typedef int64_t FrameCnt; -/** +/** * closure representing the execution context of a job. * The information reachable through this closure is specific * for this kind of job, but static and typically shared among * all jobs for a given feed and segment of the timeline - */ + */ struct lumiera_jobClosure { /* placeholder */ }; typedef struct lumiera_jobClosure* LumieraJobClosure; @@ -279,8 +279,8 @@ namespace engine { return this->parameter.invoKey; } - JobKind getKind() const; - bool isValid() const; + JobKind getKind() const; + bool isValid() const; bool usesClosure (JobClosure const&) const; @@ -332,4 +332,4 @@ size_t lumiera_job_get_hash (LumieraJobDefinition); #ifdef __cplusplus } #endif -#endif +#endif /*BACKEND_ENGINE_JOB_H*/ diff --git a/src/backend/file-handling.c b/src/backend/file-handling.c index daa9f49c7..df5326ded 100644 --- a/src/backend/file-handling.c +++ b/src/backend/file-handling.c @@ -33,7 +33,7 @@ LUMIERA_ERROR_DEFINE (FILE_CHANGED, "File changed unexpected"); -LUMIERA_ERROR_DEFINE (FILE_NOMMAPINGS, "MMapings (chunksize/bias) not initialized"); +LUMIERA_ERROR_DEFINE (FILE_NOMMAPINGS, "MMapings (chunksize/bias) not initialised"); diff --git a/src/backend/file.h b/src/backend/file.h index 8b8b94ca5..7a8aac5bf 100644 --- a/src/backend/file.h +++ b/src/backend/file.h @@ -1,5 +1,5 @@ /* - file.h - interface to files by filename + FILE.h - interface to files by filename Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,32 +17,33 @@ 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. + */ -#ifndef LUMIERA_FILE_H -#define LUMIERA_FILE_H + +/** @file file.h + ** File management. + ** Handling Files is split into different classes: + ** 1. The 'lumiera_file' class which acts as interface to the outside for managing files. + ** 'lumiera_file' is addressed by the name of the file. Since files can have more than one name (hardlinks) + ** many 'lumiera_file' can point to a single 'lumiera_filedescriptor' + ** 2. The 'lumiera_filedescriptor' class which does the real work managing the file in the back. + ** 3. Since OS-filehandles are a limited resource we access the lazily as 'lumiera_filehandle' which are + ** managed in a 'lumiera_filehandlecache' + */ + +#ifndef BACKEND_FILE_H +#define BACKEND_FILE_H #include "lib/mutex.h" #include "lib/llist.h" #include "lib/error.h" -//NOBUG_DECLARE_FLAG (file); LUMIERA_ERROR_DECLARE(FILE_CHANGED); LUMIERA_ERROR_DECLARE(FILE_NOMMAPINGS); -/** - * @file - * File management - * Handling Files is splitted into different classes: - * 1. The 'lumiera_file' class which acts as interface to the outside for managing files. - * 'lumiera_file' is addressed by the name of the file. Since files can have more than one name (hardlinks) - * many 'lumiera_file' can point to a single 'lumiera_filedescriptor' - * 2. The 'lumiera_filedescriptor' class which does the real work managing the file in the back. - * 3. Since OS-filehandles are a limited resource we access the lazily as 'lumiera_filehandle' which are - * managed in a 'lumiera_filehandlecache' - */ typedef struct lumiera_file_struct lumiera_file; typedef lumiera_file* LumieraFile; @@ -55,17 +56,17 @@ typedef lumiera_file* LumieraFile; /** * File modes: - * LUMIERA_FILE_READONLY existing file for reading only - * LUMIERA_FILE_READWRITE existing file for reading and writing - * LUMIERA_FILE_CREATE non-existing file for reading and writing - * LUMIERA_FILE_RECREATE remove and recreated existing, file for reading and writing + * - \c LUMIERA_FILE_READONLY existing file for reading only + * - \c LUMIERA_FILE_READWRITE existing file for reading and writing + * - \c LUMIERA_FILE_CREATE non-existing file for reading and writing + * - \c LUMIERA_FILE_RECREATE remove and recreated existing, file for reading and writing */ #define LUMIERA_FILE_READONLY (O_RDONLY | O_LARGEFILE | O_NOATIME) #define LUMIERA_FILE_READWRITE (O_RDWR | O_LARGEFILE | O_NOATIME) #define LUMIERA_FILE_CREATE (O_RDWR | O_LARGEFILE | O_NOATIME | O_CREAT | O_EXCL) #define LUMIERA_FILE_RECREATE (O_RDWR | O_LARGEFILE | O_NOATIME | O_CREAT | O_TRUNC) -/* creat and excl flags will be masked out for descriptor lookup */ +/* \c creat and \c excl flags will be masked out for descriptor lookup */ #define LUMIERA_FILE_MASK ~(O_CREAT | O_EXCL | O_TRUNC) struct lumiera_file_struct @@ -78,7 +79,7 @@ struct lumiera_file_struct /** - * Initialize a file structure. + * Initialise a file structure. * @param self pointer to the file structure * @param name filename * @param flags open flags @@ -90,7 +91,7 @@ lumiera_file_init (LumieraFile self, const char* name, int flags); /** * Destroy a file structure. - * frees all associated resources, releases the filedescriptor etc. + * frees all associated resources, releases the file descriptor etc. * @param self file structure to be destroyed * @param do_unlink if 1 then delete the file physically from disk (only the associated name) * @return self @@ -128,8 +129,8 @@ lumiera_file_delete_unlink (LumieraFile self); /** * Get a POSIX filehandle for a file. * Filehandles are opened on demand and must be acquired for use. - * Using filehandles is refcounted and might be nested. - * After using them they must be released which puts them back into filehandlecache aging. + * The use of filehandles is refcounted and might be nested. + * After using them they must be released which puts them back into filehandle cache aging. * @param self file structure * @return POSIX filehandle or -1 on error, check lumiera_error() to retrieve the errorcode * Currently only LUMIERA_ERROR_ERRNO will be raised but this might change in future. @@ -169,8 +170,8 @@ lumiera_file_release_mmap (LumieraFile self, LumieraMMap map); /** - * helper macro for acquireing and releasing maped regions - * @param nobugflag yet unused + * helper macro for acquiring and releasing maped regions + * @param nobugflag unused for now * @param file the file from from where to acquire the mapped region * @param start the start offset for the mmaped region * @param size the length of the requested block @@ -210,8 +211,8 @@ lumiera_file_checkflags (LumieraFile self, int flags); /** * Set the chunksize for mapping operations - * can only set once for a filedescriptor, subsequent calls are no-ops - * @param chunksize allocation/mmaping granularity, must be 2's exponent of pagesize + * can only set once for a file descriptor, subsequent calls are no-ops + * @param chunksize allocation/mmaping granularity, must be 2's exponent of page size * @param bias offset to shift chunks, used for stepping over a header for example. * @return the effective chunksize used for the file */ @@ -237,9 +238,9 @@ lumiera_file_bias_get (LumieraFile self); /** - * Place and remove locks on a file + * Place and remove locks on a file. * This locks are per thread and lock the file across multiple lumiera processes - * (or any other programm which repects advisory file locking). + * (or any other program which respect to advisory file locking). * Only exclusive locks over the whole file are supported for initially accessing * a file, other locking is done somewhere else. */ @@ -277,12 +278,4 @@ lumiera_file_unlock (LumieraFile self); -#endif - -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ +#endif /*BACKEND_FILE_H*/ diff --git a/src/backend/filedescriptor.c b/src/backend/filedescriptor.c index db5b96de5..b7320bf1c 100644 --- a/src/backend/filedescriptor.c +++ b/src/backend/filedescriptor.c @@ -1,5 +1,5 @@ /* - filedescriptor.c - file handling + FileDescriptor - file handling Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/mutex.h" @@ -38,7 +40,7 @@ -/* lookup and creation of files, initialized in backend.c */ +/* lookup and creation of files, initialised in backend.c */ lumiera_mutex lumiera_filecreate_mutex; @@ -221,7 +223,7 @@ lumiera_filedescriptor_delete (LumieraFiledescriptor self, const char* name) lumiera_filedescriptorregistry_remove (self); - TODO ("destruct other members (WIP)"); + TODO ("destroy other members (WIP)"); lumiera_mmapings_delete (self->mmapings); diff --git a/src/backend/filedescriptor.h b/src/backend/filedescriptor.h index 8f73bfb2c..870cbb7d2 100644 --- a/src/backend/filedescriptor.h +++ b/src/backend/filedescriptor.h @@ -1,5 +1,5 @@ /* - filedescriptor.h - file handling + FILEDESCRIPTOR.h - file handling Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -19,8 +19,14 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -#ifndef LUMIERA_FILEDESCRIPTOR_H -#define LUMIERA_FILEDESCRIPTOR_H + +/** @file filedescriptor.h + ** File descriptors are the underlying working horse in accessing files. + ** All information associated with managing a file is kept here. + */ + +#ifndef BACKEND_FILEDESCRIPTOR_H +#define BACKEND_FILEDESCRIPTOR_H #include "lib/mutex.h" #include "lib/rwlock.h" @@ -40,12 +46,7 @@ typedef lumiera_filedescriptor* LumieraFiledescriptor; #include "backend/file.h" #include "backend/mmapings.h" -/** - * @file - * Filedescriptors. - * Filedescriptors are the underlying working horse in accessing files. - * All information associated with managing a file is kept here. - */ + struct lumiera_filedescriptor_struct { /** node for the lookup tree */ @@ -77,6 +78,7 @@ struct lumiera_filedescriptor_struct /** file locking, a rwlock for thread locking */ lumiera_rwlock filelock; + /** readlock counter for releasing the file lock, -1 for write lock, 0 = unlocked */ int lock_cnt; RESOURCE_USER (filelock_rh); @@ -119,7 +121,7 @@ lumiera_filedescriptor_samestat (LumieraFiledescriptor self, struct stat* stat); /** * Allocate a new filedescriptor cloned from a template * @param template the source filedescriptor - * @return the constrccted filedescriptor + * @return the constructed filedescriptor */ LumieraFiledescriptor lumiera_filedescriptor_new (LumieraFiledescriptor template); @@ -148,11 +150,4 @@ lumiera_filedescriptor_unlock (LumieraFiledescriptor self); -#endif -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ +#endif /*BACKEND_FILEDESCRIPTOR_H*/ diff --git a/src/backend/filedescriptorregistry.c b/src/backend/filedescriptorregistry.c index 52dc8c3ed..9f7100de9 100644 --- a/src/backend/filedescriptorregistry.c +++ b/src/backend/filedescriptorregistry.c @@ -1,5 +1,5 @@ /* - filedescriptorregistry.c - register all files in use + FiledescriptorRegistry - registry for tracking all files in use Copyright (C) Lumiera.org 2008, 2010, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/safeclib.h" @@ -29,10 +31,8 @@ #include "backend/filedescriptorregistry.h" -/* - Filedescriptor registry - - This registry stores all acquired filedescriptors for lookup, they will be freed when not referenced anymore. +/** + * the global registry for file descriptors. */ static PSplay filedescriptorregistry = NULL; static lumiera_mutex filedescriptorregistry_mutex; @@ -110,7 +110,7 @@ lumiera_filedescriptorregistry_destroy (void) LumieraFiledescriptor lumiera_filedescriptorregistry_ensure (LumieraFiledescriptor template) { - REQUIRE (filedescriptorregistry, "not initialized"); + REQUIRE (filedescriptorregistry, "not initialised"); LumieraFiledescriptor ret = NULL; @@ -136,9 +136,6 @@ lumiera_filedescriptorregistry_ensure (LumieraFiledescriptor template) } -/** - * Removes a Filedescriptor from the registry. - */ void lumiera_filedescriptorregistry_remove (LumieraFiledescriptor self) { diff --git a/src/backend/filedescriptorregistry.h b/src/backend/filedescriptorregistry.h index 2faea51f9..b7c8d9ba7 100644 --- a/src/backend/filedescriptorregistry.h +++ b/src/backend/filedescriptorregistry.h @@ -1,5 +1,5 @@ /* - filedescriptorregistry.h - register all files in use + FILEDESCRIPTORREGISTRY.h - registry for tracking all files in use Copyright (C) Lumiera.org 2008, 2010, Christian Thaeter @@ -17,24 +17,33 @@ 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. + */ -#ifndef LUMIERA_FILEDESCRIPTORREGISTRY_H -#define LUMIERA_FILEDESCRIPTORREGISTRY_H + +/** @file filedescriptorregistry.h + ** Registry for used file descriptors. + ** This registry stores all acquired file descriptors for lookup, + ** they will be freed when not referenced anymore. + */ + +#ifndef BACKEND_FILEDESCRIPTORREGISTRY_H +#define BACKEND_FILEDESCRIPTORREGISTRY_H #include "backend/filedescriptor.h" /** - * Initialize the global filedescriptor registry. - * Opening hardlinked files will be targeted to the same filedescriptor. - * This function never fails but dies on error. TODO backend/subsystem failure + * Initialise the global file descriptor registry. + * Opening hard linked files will be targeted to the same file descriptor. + * This function never fails but dies on error. + * @todo proper backend/subsystem failure */ void lumiera_filedescriptorregistry_init (void); /** - * Destroy and free the global filedescriptor registry. + * Destroy and free the global file descriptor registry. * Never fails. */ void @@ -48,11 +57,11 @@ lumiera_filedescriptorregistry_destroy (void); LumieraFiledescriptor lumiera_filedescriptorregistry_ensure (LumieraFiledescriptor template); -/** - * Removes a Filedescriptor from the registry. - */ + +/** Removes a file descriptor from the registry. */ void lumiera_filedescriptorregistry_remove (LumieraFiledescriptor self); -#endif + +#endif /*BACKEND_FILEDESCRIPTORREGISTRY_H*/ diff --git a/src/backend/filehandle.c b/src/backend/filehandle.c index 409d6ed32..4f17f295a 100644 --- a/src/backend/filehandle.c +++ b/src/backend/filehandle.c @@ -1,5 +1,5 @@ /* - filehandle - filehandle management and caching + FileHandle - filehandle management and caching Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/llist.h" @@ -29,6 +31,8 @@ #include + + LumieraFilehandle lumiera_filehandle_init (LumieraFilehandle self, LumieraFiledescriptor desc) { @@ -78,7 +82,7 @@ lumiera_filehandle_handle (LumieraFilehandle self) fd = open (lumiera_filedescriptor_name (self->descriptor), lumiera_filedescriptor_flags (self->descriptor) & LUMIERA_FILE_MASK); if (fd == -1) { - FIXME ("Handle EMFILE etc with the resourcecollector"); + //////////////////////TODO Handle EMFILE etc with the resourcecollector LUMIERA_ERROR_SET_CRITICAL (file, ERRNO, lumiera_filedescriptor_name (self->descriptor)); } else diff --git a/src/backend/filehandle.h b/src/backend/filehandle.h index 1290a52e8..6b6180388 100644 --- a/src/backend/filehandle.h +++ b/src/backend/filehandle.h @@ -1,5 +1,5 @@ /* - filehandle - filehandle management and caching + FILEHANDLE - filehandle management and caching Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,9 +17,19 @@ 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. + */ -#ifndef LUMIERA_FILEHANDLE_H -#define LUMIERA_FILEHANDLE_H + + +/** @file filehandle.h + ** Filehandles manage the underlying POSIX filehandle for a file descriptor. + ** Since we want to support handling of more files than POSIX filehandles are available + ** on a common system the filehandles are opened, cached and closed on demand, see 'filehandlecache'. + ** Access to filehandles is locked from elsewhere (filedescriptor, filehandlecache) + */ + +#ifndef BACKEND_FILEHANDLE_H +#define BACKEND_FILEHANDLE_H #include "lib/error.h" #include "lib/llist.h" @@ -31,14 +41,6 @@ typedef lumiera_filehandle* LumieraFilehandle; //NOBUG_DECLARE_FLAG (filehandle); -/** - * @file - * Filehandles. - * Filehandles manage the underlying POSIX filehandle for a filedescriptor. - * Since we want to support handling of more files than POSIX filehandles are available on a common system - * the filehandles are opened, cached and closed on demand, see 'filehandlecache'. - * Access to filehandles is locked from elsewhere (filedescriptor, filehandlecache) - */ /** @@ -52,15 +54,17 @@ struct lumiera_filehandle_struct LumieraFiledescriptor descriptor; }; + /** - * Initialize filehandle structure. - * @param self filehandle sttructure to be initialized + * Initialise filehandle structure. + * @param self filehandle structure to be initialised * @param descriptor on which this filehandle will be attached * @return new filehandle structure */ LumieraFilehandle lumiera_filehandle_init (LumieraFilehandle self, LumieraFiledescriptor descriptor); + /** * Allocate a new filehandle structure. * @param descriptor on which this filehandle will be attached @@ -71,9 +75,9 @@ lumiera_filehandle_new (LumieraFiledescriptor descriptor); /** - * destroy the resources associated eith a filehandle structure. - * This function is used by the filehandlecache to recycle filehandle structs. - * @param node pointer to the cachenode member of a struct filehandle + * destroy the resources associated either a filehandle structure. + * This function is used by the filehandle cache to recycle filehandle structs. + * @param node pointer to the cache node member of a struct filehandle * @return pointer to the start of the memory of the destroyed filehandle */ void* @@ -85,7 +89,7 @@ lumiera_filehandle_handle (LumieraFilehandle self); /** - * just accessor, no saftey net + * just accessor, no safety net */ static inline int lumiera_filehandle_get (LumieraFilehandle self) @@ -94,4 +98,4 @@ lumiera_filehandle_get (LumieraFilehandle self) return self->fd; } -#endif +#endif /*BACKEND_FILEHANDLE_H*/ diff --git a/src/backend/filehandlecache.c b/src/backend/filehandlecache.c index 6090cdd8c..b45bdf42c 100644 --- a/src/backend/filehandlecache.c +++ b/src/backend/filehandlecache.c @@ -1,5 +1,5 @@ /* - filehandlecache - filehandle management and caching + FileHandleCache - filehandle management and caching Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/safeclib.h" @@ -26,18 +28,21 @@ #include "backend/filehandlecache.h" -/* errors */ LUMIERA_ERROR_DEFINE (FILEHANDLECACHE_NOHANDLE, "No filehandle available"); +/** + * the global cache for file handles. + */ LumieraFilehandlecache lumiera_fhcache = NULL; + void lumiera_filehandlecache_new (int max_entries) { - REQUIRE (!lumiera_fhcache, "Filehandlecache already initialized"); + REQUIRE (!lumiera_fhcache, "Filehandlecache already initialised"); lumiera_fhcache = lumiera_malloc (sizeof (lumiera_filehandlecache)); lumiera_mrucache_init (&lumiera_fhcache->cache, lumiera_filehandle_destroy_node); diff --git a/src/backend/filehandlecache.h b/src/backend/filehandlecache.h index ca130cfbd..2692db3ba 100644 --- a/src/backend/filehandlecache.h +++ b/src/backend/filehandlecache.h @@ -1,5 +1,5 @@ /* - filehandlecache - filehandle management and caching + FILEHANDLECACHE - filehandle management and caching Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,9 +17,20 @@ 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. + */ -#ifndef LUMIERA_FILEHANDLECACHE_H -#define LUMIERA_FILEHANDLECACHE_H + + +/** @file filehandlecache.h + ** Caching and management of filehandles. + ** The number of filehandles a program can held open is usually limited, since we want to support + ** using a less limited number of files and closing/opening for each operation is expensive, we + ** provide a cache to keep the most frequent used files open and gracefully close/recycle unused filehandles. + ** The filehandle cache defined here protects all operations on the cache with a mutex. + */ + +#ifndef BACKEND_FILEHANDLECACHE_H +#define BACKEND_FILEHANDLECACHE_H #include "lib/error.h" #include "lib/mrucache.h" @@ -30,19 +41,9 @@ typedef lumiera_filehandlecache* LumieraFilehandlecache; #include "backend/filehandle.h" -/** - * @file - * Filehandle management and caching - * The number of filehandles a program can held open is usually limited, since we want to support - * using a less limited number of files and closing/opening for each operation is expensive, we - * provide a cache to keep the most frequent used files open and gracefully close/recycle unused filehandles. - * The filehandlecache defined here protects all operations on the cache with a mutex. - */ -/* - File handle cache manages file handles - */ +/** File handle cache manages file handles */ struct lumiera_filehandlecache_struct { lumiera_mrucache cache; @@ -52,7 +53,7 @@ struct lumiera_filehandlecache_struct }; /** - * Initializes the filehandle cache. + * Initialises the filehandle cache. * @param max_entries number how much filehandles shall be managed * The number of elements the cache can hold is static and should be * determined by sysconf (_SC_OPEN_MAX) minus some (big) safety margin. @@ -94,4 +95,6 @@ lumiera_filehandlecache_checkout (LumieraFilehandle handle); void lumiera_filehandlecache_checkin (LumieraFilehandle handle); -#endif + + +#endif /*BACKEND_FILEHANDLECACHE_H*/ diff --git a/src/backend/fileheader.c b/src/backend/fileheader.c index e10db4c8f..c248acded 100644 --- a/src/backend/fileheader.c +++ b/src/backend/fileheader.c @@ -1,5 +1,5 @@ /* - fileheader.c - Definitions of generic lumiera fileheaders and identification + Fileheader - Definitions of generic lumiera file headers and identification Copyright (C) Lumiera.org 2010, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "lib/tmpbuf.h" @@ -25,24 +27,19 @@ #include "backend/file.h" #include "include/logging.h" -//TODO: internal/static forward declarations// - - #include -/** - * @file - * - */ -LUMIERA_ERROR_DEFINE (FILEHEADER_NOWRITE, "File is not writeable"); + +LUMIERA_ERROR_DEFINE (FILEHEADER_NOWRITE, "File is not writable"); LUMIERA_ERROR_DEFINE (FILEHEADER_HEADER, "Error in header"); LUMIERA_ERROR_DEFINE (FILEHEADER_FLAGS, "Inconsistent Flags"); LUMIERA_ERROR_DEFINE (FILEHEADER_FLAGSPACE, "No more space for flags left"); LUMIERA_ERROR_DEFINE (FILEHEADER_ENDIANESS, "Unsupported Endianess"); + lumiera_fileheader lumiera_fileheader_create (LumieraFile file, char* fourcc, int version, size_t size, const char* flags) { @@ -109,7 +106,7 @@ lumiera_fileheader_open (LumieraFile file, char* fourcc, size_t size, const char goto err; } - TODO("only clear flags when file is writeable"); + ////////////////////TODO only clear flags when file is writable! lumiera_fileheader_flags_clear (&self, flags_remove); static uint64_t endianess_mark = LUMIERA_FILEHEADER_ENDIANMAGIC; @@ -204,6 +201,7 @@ lumiera_fileheader_flags_set (LumieraFileheader self, const char* flags) return self; } + /** * Clear flags if present */ diff --git a/src/backend/fileheader.h b/src/backend/fileheader.h index a14abd97f..9ed8f4b5f 100644 --- a/src/backend/fileheader.h +++ b/src/backend/fileheader.h @@ -1,5 +1,5 @@ /* - fileheader.h - Definitions of generic lumiera fileheaders and identification + FILEHEADER.h - Definitions of generic lumiera file headers and identification Copyright (C) Lumiera.org 2010, Christian Thaeter @@ -17,13 +17,28 @@ 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. + */ -#ifndef LUMIERA_FILEHEADER_H -#define LUMIERA_FILEHEADER_H + +/** @file fileheader.h + ** Common header format to identify various kinds of files. + ** Lumiera creates some files on itself, caches, indexes and so on. + ** Here we define a unified header format for identifying and handling these files. + ** + ** Most of this files store binary data in host order for performance reasons and are not yet + ** intended to be transfered between computers. While the transferability depends on the + ** concrete implementation later and is not constrained here. + ** + */ + +#ifndef BACKEND_FILEHEADER_H +#define BACKEND_FILEHEADER_H #include "lib/error.h" + + LUMIERA_ERROR_DECLARE (FILEHEADER_NOWRITE); LUMIERA_ERROR_DECLARE (FILEHEADER_HEADER); LUMIERA_ERROR_DECLARE (FILEHEADER_FLAGS); @@ -46,17 +61,6 @@ typedef lumiera_fileheader_raw* LumieraFileheaderRaw; #include -/** - * @file - * - * Lumiera creates some files on itself, caches, indexes and so on. - * Here we define a unified header format for identifying and handling these files. - * - * Most of this files store binary data in host order for performance reasons an are not yet - * intended to be transfered between computers. While the transferability depends on the - * concrete implementation later and is not contstrained here. - * - */ #ifndef LUMIERA_PACKED @@ -64,7 +68,7 @@ typedef lumiera_fileheader_raw* LumieraFileheaderRaw; #endif /** - * A basic fileheader + * A basic file header * On-Disk representation starts with 32 bytes identifying the file. * The first 32 bytes are human readable text. */ @@ -76,12 +80,12 @@ struct LUMIERA_PACKED lumiera_fileheader_raw_struct char version[3]; /** always '\n' */ char newline1; - /** freeform string, comment or so on, initialized to spaces */ + /** free form string, comment or so on, initialised to spaces */ char meta[15]; /** always '\n' */ char newline2; - /** initialized to spaces, flags are single chars, unsorted */ + /** Initialised to spaces, flags are single chars, unsorted */ char flags[6]; /** always '\n' */ char newline3; @@ -93,7 +97,8 @@ struct LUMIERA_PACKED lumiera_fileheader_raw_struct }; /** - * Fileheader flags are chars to make this easily inspectable, these add another human readable line to the header + * File header flags are chars to support debugging and inspection, + * these add another human readable line to the header. */ /** file is clean */ @@ -107,7 +112,7 @@ struct LUMIERA_PACKED lumiera_fileheader_raw_struct /** - * A fileheader object encapsulates the underlying mmap object which keeps the + * A file header object encapsulates the underlying mmap object which keeps the * raw header data in memory and and the dereferenced thereof. */ struct lumiera_fileheader_struct @@ -118,15 +123,15 @@ struct lumiera_fileheader_struct /** - * Create a fileheader on a file open for writing. - * This overwrites any existing date, take care. The created fileheader is mmaped into memory - * and must be closed after use. The File should be locked for operations on the fileheader. + * Create a file header on a file open for writing. + * This overwrites any existing date, take care. The created file header is mmaped into memory + * and must be closed after use. The File should be locked for operations on the file header. * @param file The file on which to create the header. * @param fourcc pointer to a string of length 4 * @param version version number for the header (should be incremented after changes) * the value '0' is reserved for experimental versions. * @param size The actual size of all header data, including following format specific data. - * @param flags initial flags which should be set (dont include CLEAN here, should be set on close) + * @param flags initial flags which should be set (don't include CLEAN here, should be set on close) * @return A lumiera_fileheader object by value, .header and .map are set to NULL on error. */ lumiera_fileheader @@ -134,9 +139,9 @@ lumiera_fileheader_create (LumieraFile file, char* fourcc, int version, size_t s /** - * Open an existing fileheader. - * The underlying file might be readonly. The opened fileheader is mmaped into memory - * and must be closed after use. The File should be locked for operations on the fileheader. + * Open an existing file header. + * The underlying file might be readonly. The opened file header is mmaped into memory + * and must be closed after use. The File should be locked for operations on the file header. * @param file The file on which to open the header. * @param fourcc pointer to a string of length 4 with the expected identifier for the file * @param size The actual size of all header data, including following format specific data @@ -149,8 +154,8 @@ lumiera_fileheader_open (LumieraFile file, char* fourcc, size_t size, const char /** - * Closes a previously created or opened fileheader. - * @param self the fileheader to close. + * Closes a previously created or opened file header. + * @param self the file header to close. * @param flags_add set this flags if not already set * no errors, no nothing returned (yet) */ @@ -159,9 +164,9 @@ lumiera_fileheader_close (LumieraFileheader self, const char* flags_add); /** - * Queries the version of a fileheader. - * @param self the fileheader to query - * @return the version stored in the fileheader or -1 on error. + * Queries the version of a file header. + * @param self the file header to query + * @return the version stored in the file header or -1 on error. */ int lumiera_fileheader_version (LumieraFileheader self); @@ -187,7 +192,7 @@ LumieraFileheader lumiera_fileheader_flags_clear (LumieraFileheader self, const char* flags); -#endif +#endif /*BACKEND_FILEHEADER_H*/ /* // Local Variables: // mode: C diff --git a/src/backend/mmap.c b/src/backend/mmap.c index 41998c60a..16d4f5328 100644 --- a/src/backend/mmap.c +++ b/src/backend/mmap.c @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/safeclib.h" @@ -30,21 +32,13 @@ #include #include -/** - * @file - * - */ - LUMIERA_ERROR_DEFINE (MMAP_NWRITE, "Backing file not writable"); LUMIERA_ERROR_DEFINE (MMAP_SPACE, "Address space exhausted"); -/** - * global mmap registry/cache - * - */ + LumieraMMap @@ -52,7 +46,7 @@ lumiera_mmap_init (LumieraMMap self, LumieraFile file, off_t start, size_t size) { TRACE (mmap_dbg); - TODO ("enforce size instead using chunksize (rounded to pagessize) for parsing headers"); + TODO ("enforce size instead using chunksize (rounded to page size) for parsing headers"); REQUIRE (self); REQUIRE (file); @@ -60,9 +54,19 @@ lumiera_mmap_init (LumieraMMap self, LumieraFile file, off_t start, size_t size) REQUIRE (size); /** - * default size for the mmapping window - * 128MB on 32 bit arch - * 2GB on 64 bit arch + * default size for the mmapping window. + * - 128MB on 32 bit arch + * - 2GB on 64 bit arch + * + * \par + * Maintaining the right[tm] mmapping size is a bit tricky: + * - We have the default mmap_window_size which will be backed off when address space gets exhausted + * - When a bigger size is requested we have to fulfil it + * - The last mmapped chunk of a file can be as small as possible when the file is readonly + * - When the file is writable, the last chunk should be rounded up to chunksize + * - All boundaries will be aligned up/down to chunk boundaries + * - Requests beyond the file end must ftruncate and map additional pages + * - Create the 'refmap' which contains a refcounter per chunk */ TODO("move the setdefaults somewhere else, backend_defaults.c or so"); #if SIZE_MAX <= 4294967295U @@ -92,16 +96,6 @@ lumiera_mmap_init (LumieraMMap self, LumieraFile file, off_t start, size_t size) TODO ("error here? or just map as asked for?"); ENSURE(chunksize); - /** - * Maintaining the right[tm] mmapping size is a bit tricky: - * - We have the default mmap_window_size which will be backed off when address space gets exhausted - * - When a bigger size is requested we have to fulfil it - * - The last mmapped chunk of a file can be as small as possible when the file is readonly - * - When the file is writable, the last chunk should be rounded up to chunksize - * - All boundaries will be aligned up/down to chunk boundaries - * - Requests beyond the file end must ftruncate and map additional pages - * - Create the 'refmap' which contains a refcounter per chunk - **/ /** * Recovering address space strategies: @@ -245,7 +239,7 @@ lumiera_mmap_init_exact (LumieraMMap self, LumieraFile file, off_t start, size_t } } - TODO ("use resourcecllector here"); + /////////////////////////TODO use resourcecllector here void* addr = mmap (NULL, size, (descriptor->flags & O_ACCMODE) == O_RDONLY ? PROT_READ : PROT_READ|PROT_WRITE, diff --git a/src/backend/mmap.h b/src/backend/mmap.h index 77f4672d0..5b2ad2ba6 100644 --- a/src/backend/mmap.h +++ b/src/backend/mmap.h @@ -1,5 +1,5 @@ /* - mmap.h - memory mapped access to files + MMAP - memory mapped access to files Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,10 +17,17 @@ 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. + */ -#ifndef LUMIERA_MMAP_H -#define LUMIERA_MMAP_H + +/** @file mmap.h + ** MMap objects cover a memory mapped range in a file. + ** They are managed through a global mmap registry/cache. + */ + +#ifndef BACKEND_MMAP_H +#define BACKEND_MMAP_H #include "lib/llist.h" @@ -36,26 +43,20 @@ typedef lumiera_mmap* LumieraMMap; #include #include -//NOBUG_DECLARE_FLAG (mmap); + + + /** - * @file - * MMap objects cover a memory maped range in a file - */ - - - -/** - * mmaped area - * + * Descriptor of a memory mapped area */ struct lumiera_mmap_struct { /** used for the mrucache when checked in the cache **/ llist cachenode; - /** all mmaps of a filedescriptor are chained in this list, used to find ranges **/ + /** all mmaps regarding a file are chained in this list, used to find ranges **/ llist searchnode; off_t start; @@ -65,14 +66,15 @@ struct lumiera_mmap_struct /** accumulated references, this is 0 when checked into the cache **/ long refcnt; - /** array with refcounters per chunk **/ - short* refmap; // TODO flexible array? + /** array with a refcounter per chunk **/ + short* refmap; ///////////////////// TODO make this a flexible array? }; + /** - * Initialize a MMap object. + * Initialise a MMap object. * The mmap objects are aligned and shifted by the chunksize and bias defined for the file - * @param self the mmap object to be initialized + * @param self the mmap object to be initialised * @param file file from which to map * @param start offset in file which must be part of the mmaped region * @param size minimum size after start to map @@ -82,9 +84,9 @@ LumieraMMap lumiera_mmap_init (LumieraMMap self, LumieraFile file, off_t start, size_t size); /** - * Initialize a MMap object. + * Initialise a MMap object. * Maps exactly the given range - * @param self the mmap object to be initialized + * @param self the mmap object to be initialised * @param file file from which to map * @param start offset in file which must be part of the mmaped region * @param size minimum size after start to map @@ -123,7 +125,7 @@ void* lumiera_mmap_destroy_node (LList node); -#endif +#endif /*BACKEND_MMAP_H*/ /* // Local Variables: // mode: C diff --git a/src/backend/mmapcache.c b/src/backend/mmapcache.c index 161a14a34..4c6e6d247 100644 --- a/src/backend/mmapcache.c +++ b/src/backend/mmapcache.c @@ -1,5 +1,5 @@ /* - mmapcache.c - handle aging of mmap objects + MMAP-Cache - handle aging of mmap objects Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,17 +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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/safeclib.h" #include "backend/mmapcache.h" -/** - * @file - * - */ LumieraMMapcache lumiera_mcache = NULL; @@ -82,7 +80,7 @@ lumiera_mmapcache_mmap_acquire (void) } else { - TRACE (mmapcache_dbg, "poped mmap from cache"); + TRACE (mmapcache_dbg, "Popped mmap from cache"); } return map; @@ -125,7 +123,7 @@ lumiera_mmapcache_age (void) LUMIERA_MUTEX_SECTION (mmapcache, &lumiera_mcache->lock) { - ret = lumiera_mrucache_age (&lumiera_mcache->cache, 10); TODO ("age nelem == 20%(configureable) of the cache"); + ret = lumiera_mrucache_age (&lumiera_mcache->cache, 10); TODO ("age nelem == 20%(configurable) of the cache"); } return ret; @@ -140,7 +138,7 @@ lumiera_mmapcache_checkout (LumieraMMap handle) LUMIERA_MUTEX_SECTION (mutex_sync, &lumiera_mcache->lock) { - TODO ("cached stats"); + ////////////////////TODO cached stats lumiera_mrucache_checkout (&lumiera_mcache->cache, &handle->cachenode); } @@ -156,7 +154,7 @@ lumiera_mmapcache_checkin (LumieraMMap handle) LUMIERA_MUTEX_SECTION (mutex_sync, &lumiera_mcache->lock) { - TODO ("cached stats"); + ////////////////////TODO cached stats lumiera_mrucache_checkin (&lumiera_mcache->cache, &handle->cachenode); } } diff --git a/src/backend/mmapcache.h b/src/backend/mmapcache.h index 2b5345696..cb8c9fe6c 100644 --- a/src/backend/mmapcache.h +++ b/src/backend/mmapcache.h @@ -1,5 +1,5 @@ /* - mmapcache.h - handle aging of mmap objects + MMAPCACHE.h - handle aging of mmap objects Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,10 +17,17 @@ 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. + */ -#ifndef LUMIERA_MMAPCACHE_H -#define LUMIERA_MMAPCACHE_H + +/** @file mmapcache.h + ** Lumiera's Mmapcache stores a MRU cache of all established mmaped memory regions which are currently not in use. + ** The mmapcache also manages the upper limit about how much memory can be mmaped. + */ + +#ifndef BACKEND_MMAPCACHE_H +#define BACKEND_MMAPCACHE_H #include "lib/error.h" #include "lib/mrucache.h" @@ -34,11 +41,8 @@ typedef lumiera_mmapcache* LumieraMMapcache; #include -/** - * @file - * Mmapcache stores a MRU cache of all established mmaped memory regions which are currently not in use. - * The mmapcache also manages the upper limit about how much memory can be mmaped. - */ + + struct lumiera_mmapcache_struct { @@ -51,8 +55,8 @@ struct lumiera_mmapcache_struct /** - * Initializes the mmapcache. - * @param limit the mmapcache will drop elements when the sum of all mmapings gives over limit + * Initialises the mmapcache. + * @param limit the mmapcache will drop elements when the sum of all mmappings gives over limit */ void lumiera_mmapcache_new (size_t limit); @@ -67,9 +71,9 @@ lumiera_mmapcache_delete (void); /** * Get a fresh mmap object. - * when mmaped_limit is reached, the oldest mmap object gets dropped else a new allocated object - * is returned - * @return the new uninitialized mmap (void* because this is uninitialized) + * when mmaped_limit is reached, the oldest mmap object gets dropped else + * a new allocated object is returned + * @return the new uninitialised mmap (void* because this is uninitialised) */ void* lumiera_mmapcache_mmap_acquire (void); @@ -95,7 +99,7 @@ lumiera_mmapcache_forget (LumieraMMap map); /** * Destroy and free the nelem oldest elements. * Used to free up resources and memory. - * @return nelem-(numer of elements which got freed), that is 0 if all requested elements got freed + * @return nelem-(number of elements which got freed), that is 0 if all requested elements got freed */ int lumiera_mmapcache_age (void); @@ -116,7 +120,8 @@ lumiera_mmapcache_checkout (LumieraMMap handle); void lumiera_mmapcache_checkin (LumieraMMap handle); -#endif + +#endif /*BACKEND_MMAPCACHE_H*/ /* // Local Variables: // mode: C diff --git a/src/backend/mmapings.c b/src/backend/mmapings.c index a751b1b89..fe648362c 100644 --- a/src/backend/mmapings.c +++ b/src/backend/mmapings.c @@ -1,5 +1,5 @@ /* - mmapings.c - manage ranges of mmaped areas on a filedescriptor + MMapings - manage ranges of mmaped areas on a file descriptor Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/mutex.h" @@ -28,11 +30,6 @@ #include "backend/mmapcache.h" -/** - * @file - * - */ - LumieraMMapings lumiera_mmapings_init (LumieraMMapings self, LumieraFile file, size_t chunksize, size_t bias) @@ -102,7 +99,7 @@ lumiera_mmapings_mmap_acquire (LumieraMMapings self, LumieraFile file, off_t sta /* find first matching mmap, crude way */ LLIST_FOREACH (&self->mmaps, node) { - TODO ("improve this selection algorithm, choose mmaps by size, move mfu to head etc"); + ////////////TODO improve the algorithm used here: choose mmaps by size, move mfu to head etc... LumieraMMap mmap = LLIST_TO_STRUCTP (node, lumiera_mmap, searchnode); diff --git a/src/backend/mmapings.h b/src/backend/mmapings.h index 39cf7aa9f..a6f05652f 100644 --- a/src/backend/mmapings.h +++ b/src/backend/mmapings.h @@ -1,5 +1,5 @@ /* - mmapings.h - manage ranges of mmaped areas on a filedescriptor + MMAPINGS.h - manage ranges of mmaped areas on a file descriptor Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,10 +17,16 @@ 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. + */ -#ifndef LUMIERA_MMAPINGS_H -#define LUMIERA_MMAPINGS_H + +/** @file mmapings.h + ** Manage the mmap objects of a file. + */ + +#ifndef BACKEND_MMAPINGS_H +#define BACKEND_MMAPINGS_H #include "lib/mutex.h" #include "lib/llist.h" @@ -34,13 +40,8 @@ typedef lumiera_mmapings* LumieraMMapings; #include -//NOBUG_DECLARE_FLAG (mmapings); -/** - * @file - * Manage the mmap objects of a file - * - */ + struct lumiera_mmapings_struct { @@ -48,7 +49,7 @@ struct lumiera_mmapings_struct llist mmaps; /** - * chunkssize is the smallest granularity which is used for mmapping files, it + * chunksize is the smallest granularity which is used for mmapping files, it * should reflect the intended file usage, that is 'pagesize' for small or non growing * files and some MB for media files. Must be a 2's exponent of pagesize. **/ @@ -63,31 +64,24 @@ struct lumiera_mmapings_struct lumiera_mutex lock; }; -/** - * initialize mmapings container - * - */ + + +/** initialise mmapings container */ LumieraMMapings lumiera_mmapings_init (LumieraMMapings self, LumieraFile file, size_t chunksize, size_t bias); -/** - * destroy mmapings container and free all resources. - * - */ + +/** destroy mmapings container and free all resources. */ LumieraMMapings lumiera_mmapings_destroy (LumieraMMapings self); -/** - * allocate and initialize new mmapings container - * - */ + +/** allocate and initialise new mmapings container */ LumieraMMapings lumiera_mmapings_new (LumieraFile file, size_t chunksize, size_t bias); -/** - * destroy and free mmapings container and all its resources - * - */ + +/** destroy and free mmapings container and all its resources */ void lumiera_mmapings_delete (LumieraMMapings self); @@ -106,7 +100,6 @@ lumiera_mmapings_mmap_acquire (LumieraMMapings self, LumieraFile file, off_t sta /** * release a previously acquired MMap object * @param self mmapings to which the map belongs - * @param acquirer holding node * @param map object to be released */ void @@ -115,7 +108,7 @@ lumiera_mmapings_release_mmap (LumieraMMapings self, LumieraMMap map); -#endif +#endif /*BACKEND_MMAPINGS_H*/ /* // Local Variables: // mode: C diff --git a/src/backend/resourcecollector.c b/src/backend/resourcecollector.c index ec9dce348..1dccc5e5e 100644 --- a/src/backend/resourcecollector.c +++ b/src/backend/resourcecollector.c @@ -1,5 +1,5 @@ /* - resourcecollector.c - manage/collect resources when they get short + ResourceCollector - manage/collect resources when they get short Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,18 +17,21 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/llist.h" #include "lib/mutex.h" #include "lib/safeclib.h" -#include "resourcecollector.h" +#include "backend/resourcecollector.h" #include -//NOBUG_DEFINE_FLAG (resourcecollector); /* TODO: make this a hierachy, derrive from PARENT (library) ? */ + + llist lumiera_resourcecollector_registry[LUMIERA_RESOURCE_END]; lumiera_mutex lumiera_resourcecollector_lock; diff --git a/src/backend/resourcecollector.h b/src/backend/resourcecollector.h index 770b6769a..b428bdc8c 100644 --- a/src/backend/resourcecollector.h +++ b/src/backend/resourcecollector.h @@ -1,5 +1,5 @@ /* - resourcecollector.h - manage/collect resources when they get short + RESOURCECOLLECTOR.h - manage/collect resources when they get short Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,13 +17,16 @@ 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. + */ -#ifndef LUMIERA_RESOURCECOLLECTOR_H -#define LUMIERA_RESOURCECOLLECTOR_H + + +#ifndef BACKEND_RESOURCECOLLECTOR_H +#define BACKEND_RESOURCECOLLECTOR_H #include -//NOBUG_DECLARE_FLAG (resourcecollector); + /** * Resources known to the resource collector @@ -72,13 +75,13 @@ enum lumiera_resource_try LUMIERA_RESOURCE_ONE, /** try to free a small reasonable implementation defined amount of resources **/ LUMIERA_RESOURCE_SOME, - /** try to free a biggier implementation defined amount of resources **/ + /** try to free a bigger implementation defined amount of resources **/ LUMIERA_RESOURCE_MANY, /** free as much as possible **/ LUMIERA_RESOURCE_ALL, /** die! **/ LUMIERA_RESOURCE_PANIC, - /** When a handler gets unregistered it wull be called with this value to give it a chance to clean up the user 'data' **/ + /** When a handler gets unregistered it will be called with this value to give it a chance to clean up the user 'data' **/ LUMIERA_RESOURCE_UNREGISTER }; @@ -86,7 +89,7 @@ enum lumiera_resource_try /** * The type for the resource collector handler functions. * Handlers are always run with a global resourcecollector mutex locked, the user does not need to - * care about syncronization. + * care about synchronisation. * @param itr the current iteration try in freeing resources * @param data user supplied data at registration time for the handler * @param context context pointer for this collection run, might be NULL (at least for UNREGISTER and PANIC) @@ -100,8 +103,8 @@ typedef lumiera_resourcehandler* LumieraResourcehandler; /** - * Initialize the Resourcecollector. - * The resourcecollector is singleton and can be used after initialized once. + * Initialise the Resourcecollector. + * The Resourcecollector is singleton and can be used after initialised once. */ void lumiera_resourcecollector_init (void); @@ -119,7 +122,7 @@ lumiera_resourcecollector_destroy (void); * Try to free resources. * * @param which The kind of resource to be acquired - * @param iteration a pointer to a local iterator, initialized with the start + * @param iteration a pointer to a local iterator, initialised with the start * value for the loop * @param context NULL or some context dependent data for the needed resource * this is a pointer to a size_t for MEMORY and a pointer to a filename @@ -161,7 +164,7 @@ lumiera_resourcehandler_unregister (LumieraResourcehandler self); /** * Looks up a handler. - * Used to find a registered handler when the return value of register_handler() was unpractical to store. + * Used to find a registered handler when the return value of register_handler() was not practical to store. * @param resource resource for which this handler was registered * @param handler pointer to the handler function, same as used for registering * @param data opaque user-data pointer, same as used for registering @@ -170,7 +173,9 @@ lumiera_resourcehandler_unregister (LumieraResourcehandler self); LumieraResourcehandler lumiera_resourcecollector_handler_find (enum lumiera_resource resource, lumiera_resource_handler_fn handler, void* data); -#endif + + +#endif /*BACKEND_RESOURCECOLLECTOR_H*/ /* // Local Variables: // mode: C diff --git a/src/backend/threadpool.c b/src/backend/threadpool.c index ed035c209..ea01d5e46 100644 --- a/src/backend/threadpool.c +++ b/src/backend/threadpool.c @@ -1,5 +1,5 @@ /* - threadpool.c - Manage pools of threads + Threadpool - Manage pools of threads Copyright (C) Lumiera.org 2009, Michael Ploujnikov @@ -17,30 +17,24 @@ 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. -*/ -//TODO: Support library includes// +* *****************************************************/ + #include "include/logging.h" #include "lib/safeclib.h" - -//TODO: Lumiera header includes// #include "backend/threadpool.h" -//TODO: internal/static forward declarations// -static lumiera_threadpool threadpool; - -//TODO: System includes// #include -/** - * @file - * - */ LUMIERA_ERROR_DEFINE(THREADPOOL_OFFLINE, "tried to acquire thread while threadpool is not available"); -//code goes here// + + +static lumiera_threadpool threadpool; + + void lumiera_threadpool_init(void) @@ -71,7 +65,7 @@ lumiera_threadpool_destroy(void) LUMIERA_CONDITION_SECTION (cond_sync, &threadpool.pool[i].sync) threadpool.pool[i].status = LUMIERA_THREADPOOL_OFFLINE; - /* wait that all theads have finished */ + /* wait that all threads have finished */ for (int i = 0; i < LUMIERA_THREADCLASS_COUNT; ++i) { LUMIERA_CONDITION_SECTION (cond_sync, &threadpool.pool[i].sync) @@ -104,7 +98,6 @@ lumiera_threadpool_destroy(void) } /** - * * @return thread handle or NULL on error (lumiera error will be set) */ LumieraThread @@ -130,7 +123,7 @@ lumiera_threadpool_acquire_thread (enum lumiera_thread_class kind, TRACE (threadpool, "created thread %p", ret); /* - a newly created thread flows somewhere in the airm it isnt released yet into the idle list, + a newly created thread flows somewhere in the air; it is not yet released into the idle list, nor in the working list, While we are holding this CONDITION_SECION we can safely put it on the working list, this removes a small race. */ diff --git a/src/backend/threadpool.h b/src/backend/threadpool.h index 6f80c8bb9..509205ac1 100644 --- a/src/backend/threadpool.h +++ b/src/backend/threadpool.h @@ -1,5 +1,5 @@ /* - threadpool.h - Manage pools of threads + THREADPOOL.h - Manage pools of threads Copyright (C) Lumiera.org 2009, Michael Ploujnikov @@ -17,31 +17,21 @@ 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. + */ -#ifndef LUMIERA_THREADPOOL_H -#define LUMIERA_THREADPOOL_H -//TODO: Support library includes// +#ifndef BACKEND_THREADPOOL_H +#define BACKEND_THREADPOOL_H + #include "lib/condition.h" #include "lib/llist.h" - -//TODO: Forward declarations// - - -//TODO: Lumiera header includes// #include "threads.h" -//TODO: System includes// #include -/** - * @file - * - */ -//TODO: declarations go here// /** * Acquire a thread from a threadpool. @@ -81,16 +71,16 @@ struct lumiera_threadpool_struct } pool[LUMIERA_THREADCLASS_COUNT]; }; -/** - * Initialize the thread pool. - */ + +/** Initialise the thread pool. */ void lumiera_threadpool_init(void); void lumiera_threadpool_destroy(void); -#endif + +#endif /*BACKEND_THREADPOOL_H*/ /* // Local Variables: // mode: C diff --git a/src/backend/threads.c b/src/backend/threads.c index 7f580f712..811c99a64 100644 --- a/src/backend/threads.c +++ b/src/backend/threads.c @@ -1,5 +1,5 @@ /* - threads.c - Manage threads + Threads - Helper for managing threads Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,36 +17,27 @@ 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. -*/ -//TODO: Support library includes// +* *****************************************************/ + #include "include/logging.h" #include "lib/safeclib.h" +#include "backend/threads.h" - -//TODO: Lumiera header includes// -#include "threads.h" - -//TODO: internal/static forward declarations// - - -//TODO: System includes// #include #include #include -/** - * @file threads.c - * - */ + +LUMIERA_ERROR_DEFINE(THREAD, "fatal threads initialisation error"); -//code goes here// - +/** Macro for enum string trick: expands as an array of thread class name strings */ #define LUMIERA_THREAD_CLASS(name) #name, -// enum string trick: expands as an array of thread class name strings + + const char* lumiera_threadclass_names[] = { LUMIERA_THREAD_CLASSES }; @@ -59,11 +50,11 @@ const char* lumiera_threadstate_names[] = { }; #undef LUMIERA_THREAD_STATE -LUMIERA_ERROR_DEFINE(THREAD, "fatal threads initialization error"); -/* thread local storage pointing back to the thread structure of each thread */ -static pthread_key_t lumiera_thread_tls; -static pthread_once_t lumiera_thread_initialized = PTHREAD_ONCE_INIT; +/** thread local storage pointing back to the thread structure of each thread */ +static pthread_key_t lumiera_thread_tls; +static pthread_once_t lumiera_thread_initialised = PTHREAD_ONCE_INIT; + static void lumiera_thread_tls_init (void) @@ -124,8 +115,11 @@ thread_loop (void* thread) return 0; } -// when this is called it should have already been decided that the function -// shall run in parallel, as a thread + +/** + * @remarks when this is called it should have already been decided + * that the function shall run in parallel, as a thread. + */ LumieraThread lumiera_thread_run (int kind, void (*function)(void *), @@ -165,7 +159,7 @@ lumiera_thread_new (enum lumiera_thread_class kind, struct nobug_flag* flag, pthread_attr_t* attrs) { - pthread_once (&lumiera_thread_initialized, lumiera_thread_tls_init); + pthread_once (&lumiera_thread_initialised, lumiera_thread_tls_init); // TODO: do something with this string: (void) purpose; @@ -189,6 +183,7 @@ lumiera_thread_new (enum lumiera_thread_class kind, return self; } + LumieraThread lumiera_thread_destroy (LumieraThread self) { @@ -218,6 +213,7 @@ lumiera_thread_destroy (LumieraThread self) return self; } + void lumiera_thread_delete (LumieraThread self) { @@ -229,16 +225,12 @@ lumiera_thread_delete (LumieraThread self) LumieraThread lumiera_thread_self (void) { - pthread_once (&lumiera_thread_initialized, lumiera_thread_tls_init); + pthread_once (&lumiera_thread_initialised, lumiera_thread_tls_init); return pthread_getspecific (lumiera_thread_tls); } -/** - * Set a threads deadline - * A thread must finish before its deadline is hit. Otherwise it counts as stalled - * which is a fatal error which might pull the application down. - */ + LumieraThread lumiera_thread_deadline_set (struct timespec deadline) { @@ -250,10 +242,7 @@ lumiera_thread_deadline_set (struct timespec deadline) } -/** - * Extend a threads deadline - * sets the deadline to now+ms in future. This can be used to implement a heartbeat. - */ + LumieraThread lumiera_thread_deadline_extend (unsigned ms) { @@ -277,10 +266,7 @@ lumiera_thread_deadline_extend (unsigned ms) } -/** - * Clear a threads deadline - * Threads without deadline will not be checked against deadlocks (this is the default) - */ + LumieraThread lumiera_thread_deadline_clear (void) { diff --git a/src/backend/threads.h b/src/backend/threads.h index d539a3944..8dc40441e 100644 --- a/src/backend/threads.h +++ b/src/backend/threads.h @@ -1,5 +1,5 @@ /* - threads.h - Manage threads + THREADS.h - Helper for managing threads Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,36 +17,23 @@ 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. + */ -#ifndef LUMIERA_THREADS_H -#define LUMIERA_THREADS_H -//TODO: Support library includes// +#ifndef BACKEND_THREADS_H +#define BACKEND_THREADS_H + #include "lib/condition.h" - -//TODO: Forward declarations// - - -//TODO: Lumiera header includes// - - -//TODO: System includes// #include -/** - * @file threads.h - * - */ - -//TODO: declarations go here// typedef struct lumiera_thread_struct lumiera_thread; typedef lumiera_thread* LumieraThread; -// this is used for an enum string trick +/** Helper macro used for an enum string trick */ #define LUMIERA_THREAD_CLASSES \ /** mostly idle, low latency **/ \ LUMIERA_THREAD_CLASS(INTERACTIVE) \ @@ -59,9 +46,11 @@ typedef lumiera_thread* LumieraThread; /** Something to do when there is really nothing else to do **/ \ LUMIERA_THREAD_CLASS(IDLE) -// enum string trick: expands as an enum of thread classes +/** Macro for enum string trick: expands as an enum of thread classes */ #define LUMIERA_THREAD_CLASS(name) LUMIERA_THREADCLASS_##name, + + /** * Thread classes. * We define some 'classes' of threads for different purposes to abstract @@ -79,8 +68,8 @@ enum lumiera_thread_class * flag to let the decision to run the function in a thread open to the backend. * depending on load it might decide to run it sequentially. * This has some constraints: - * The Thread must be very careful with locking, better don't. - * TODO explain syncronization issues + * The Thread must be very careful with locking, better don't. + * @todo explain synchronisation issues **/ LUMIERA_THREAD_OR_NOT = 1<<8, @@ -95,6 +84,7 @@ enum lumiera_thread_class // defined in threads.c extern const char* lumiera_threadclass_names[]; + // there is some confusion between the meaning of this // on one hand it could be used to tell the current state of the thread // on the other, it is used to tell the thread which state to enter on next iteration @@ -128,6 +118,8 @@ extern const char* lumiera_threadstate_names[]; #include "threadpool.h" + + /** * The actual thread data */ @@ -136,6 +128,7 @@ struct lumiera_thread_struct llist node; // this should be first for easy casting pthread_t id; + // TODO: maybe this condition variable should be renamed when we have a better understanding of how it will be used lumiera_condition signal; // control signal, state change signal @@ -154,6 +147,7 @@ struct lumiera_thread_struct void * arguments; }; + /** * Create a thread structure. */ @@ -164,7 +158,7 @@ lumiera_thread_new (enum lumiera_thread_class kind, pthread_attr_t* attrs); /** - * Destroy and de-initialize a thread structure. + * Destroy and de-initialise a thread structure. * Memory is not freed by this function. */ LumieraThread @@ -179,12 +173,12 @@ lumiera_thread_delete (LumieraThread self); /** * Start a thread. - * Threads are implemented as procedures which take a void* and dont return anything. + * Threads are implemented as procedures which take a void* and don't return anything. * When a thread wants to pass something back to the application it should use the void* it got for * constructing the return. * * Threads must complete (return from their thread function) * * They must not call any exit() function. - * * Threads are not cancelable + * * Threads can not be cancelled * * Threads shall not handle signals (all signals will be disabled for them) unless explicitly acknowledged * * @param kind class of the thread to start @@ -209,66 +203,62 @@ lumiera_thread_run (int kind, LumieraThread lumiera_thread_self (void); + + /** - * Heartbeat and Deadlines + * Set a thread deadline. + * A thread must finish before its deadline is hit. Otherwise it counts as stalled + * which is a fatal error which might pull the application down. + * + * \par Heartbeat and Deadlines. * * Any thread can have an optional 'deadline' which must never be hit. * This deadlines are lazily checked and if hit this is a fatal error which triggers * an emergency shutdown. Thus threads are obliged to set and extend their deadlines * accordingly. - * - */ - -/** - * Set a threads deadline - * A thread must finish before its deadline is hit. Otherwise it counts as stalled - * which is a fatal error which might pull the application down. */ LumieraThread lumiera_thread_deadline_set (struct timespec deadline); /** - * Extend a threads deadline - * sets the deadline to now+ms in future. This can be used to implement a heartbeat. + * Extend the deadline of a thread + * sets the deadline to \c NOW+ms in future. This can be used to implement a heartbeat. */ LumieraThread lumiera_thread_deadline_extend (unsigned ms); /** - * Clear a threads deadline + * Clear a thread's deadline * Threads without deadline will not be checked against deadlocks (this is the default) */ LumieraThread lumiera_thread_deadline_clear (void); -/** - * Thread syncronization - * The syncronization primitives act as barrier over 2 threads, any thread reaching a syncronization - * point first is blocked until the other one reaches it too. - */ - /** - * Syncronize with another threads state - * - * this blocks until/unless the other thread reaches a syncronization point + * Synchronise with another threads state. + * This blocks until/unless the other thread reaches a synchronisation point. + * + * \par Thread synchronisation + * The synchronisation primitives act as barrier over 2 threads, any thread reaching + * a synchronisation point first is blocked until the other one reaches it too. */ LumieraThread lumiera_thread_sync_other (LumieraThread other); /** - * Syncronize current thread + * Synchronise current thread * - * this blocks until/unless the other thread reaches a syncronization point + * this blocks until/unless the other thread reaches a synchronisation point * @return on success pointer to self (opaque), or NULL on error */ LumieraThread lumiera_thread_sync (void); -// TODO implement timedsync, this is bit tricky because after a timeout, syncronization points are desynced +// TODO implement timedsync, this is bit tricky because after a timeout, synchronisation points are desynched // we possibly need some way to reset/resync this //LumieraThread //lumiera_thread_timedsync (struct timespec timeout); @@ -284,7 +274,7 @@ lumiera_thread_sync (void); lumiera_err lumiera_thread_join (LumieraThread thread); -#endif +#endif /*BACKEND_THREADS_H*/ /* // Local Variables: // mode: C diff --git a/src/common/config-interface.c b/src/common/config-interface.c index d385f2759..1f0abb1a9 100644 --- a/src/common/config-interface.c +++ b/src/common/config-interface.c @@ -1,5 +1,5 @@ /* - config-interface - Lumiera configuration interface implementation + Config-interface - Lumiera configuration interface implementation Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,19 +17,13 @@ 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. -*/ -//TODO: Support library includes// +* *****************************************************/ -//TODO: Lumiera header includes// #include "common/config-interface.h" #include "common/config.h" -//TODO: internal/static forward declarations// - - -//TODO: System includes// LUMIERA_EXPORT( @@ -155,10 +149,3 @@ lumiera_config_interface_destroy (void) #endif -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ diff --git a/src/common/config-interface.h b/src/common/config-interface.h index 1ab33a18f..ebca9d573 100644 --- a/src/common/config-interface.h +++ b/src/common/config-interface.h @@ -1,5 +1,5 @@ /* - config-interface.h - Lumiera configuration interface + CONFIG-INTERFACE.h - Lumiera configuration interface Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,21 +17,27 @@ 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 config-interface.h + ** External interface to the lumiera configuration system. + ** This file provides an interface descriptor for external entities + ** (e.g. plug-ins) to gain access to the configuration system (as + ** planned in 2008). + ** + ** @note this is unfinished work, development in this area stalled in 2008 + ** @see config.h + */ + #ifndef LUMIERA_CONFIG_INTERFACE_H #define LUMIERA_CONFIG_INTERFACE_H -//TODO: Support library includes// #include "common/interface.h" -//TODO: Forward declarations// -/** - * @file - * Declares the interface for the lumiera configuration system - */ void lumiera_config_interface_init (void); diff --git a/src/common/config-lookup.c b/src/common/config-lookup.c index 3daf24f10..a6603db60 100644 --- a/src/common/config-lookup.c +++ b/src/common/config-lookup.c @@ -1,5 +1,5 @@ /* - config_lookup.c - Lookup functions for the config subsystem + Config-lookup - Lookup functions for the config subsystem Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,14 @@ 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 config-lookup.c + ** Implementation of the lookup of configuration keys + */ + #include "include/logging.h" #include "lib/safeclib.h" @@ -29,9 +36,10 @@ /* we only use one fatal error for now, when allocation in the config system fail, something else is pretty wrong */ LUMIERA_ERROR_DEFINE (CONFIG_LOOKUP, "config lookup failure"); -/* - support functions for the splay tree -*/ + + +/* === support functions for the splay tree === */ + static int cmp_fn (const void* a, const void* b); @@ -42,10 +50,6 @@ static const void* key_fn (const PSplaynode node); -/** - * @file - * Implementation of the lookup of configuration keys - */ LumieraConfigLookup @@ -173,9 +177,7 @@ lumiera_config_lookup_item_tail_find (LumieraConfigLookup self, const char* key) -/* - Lookup entries -*/ +/* === Lookup of entries === */ LumieraConfigLookupentry lumiera_config_lookupentry_init (LumieraConfigLookupentry self, const char* key) diff --git a/src/common/config-lookup.h b/src/common/config-lookup.h index 29f5d6d18..a6816813c 100644 --- a/src/common/config-lookup.h +++ b/src/common/config-lookup.h @@ -17,10 +17,12 @@ 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. + */ -#ifndef LUMIERA_CONFIG_LOOKUP_H -#define LUMIERA_CONFIG_LOOKUP_H + +#ifndef COMMON_CONFIG_LOOKUP_H +#define COMMON_CONFIG_LOOKUP_H #include "lib/psplay.h" #include "lib/llist.h" @@ -44,7 +46,7 @@ typedef lumiera_config_lookupentry* LumieraConfigLookupentry; * Lookup of configuration keys. Configuration keys are dynamically stored in a splay tree. * This happens for defaults, loaded config files and entries which are set explicitly. * The system maintains no central registry of all possible keys. - * We store here the full keys of configentries as well as the keys of section prefixes. + * We store here the full keys of config entries as well as the keys of section prefixes. * Section prefixes are stored with a trailing dot to disambiguate them from entry keys. */ @@ -52,7 +54,7 @@ typedef lumiera_config_lookupentry* LumieraConfigLookupentry; LUMIERA_ERROR_DECLARE (CONFIG_LOOKUP); /** - * Just contains a hashtable to give sufficent abstraction. + * Just contains a hashtable to give sufficient abstraction. */ struct lumiera_config_lookup_struct { @@ -60,16 +62,16 @@ struct lumiera_config_lookup_struct }; /** - * Initialize a lookup structure. - * @param self lookup structure to be initialized + * Initialise a lookup structure. + * @param self lookup structure to be initialised * @return self on success else NULL */ LumieraConfigLookup lumiera_config_lookup_init (LumieraConfigLookup self); /** - * Destruct a lookup structure. - * @param self lookup structure to be destructed + * Destroy a lookup structure. + * @param self lookup structure to be destroyed * @return self */ LumieraConfigLookup @@ -87,9 +89,7 @@ lumiera_config_lookup_insert (LumieraConfigLookup self, LumieraConfigitem item); /** - * Add a default config item to a lookup structure. - * @internal - * This function is used internal. + * @internal Add a default config item to a lookup structure. * The item must contain a full key and not part of any 'section' * and is inserted as tail of the lookup list. * @param self lookup structure where the item shall be added @@ -132,37 +132,33 @@ LumieraConfigitem lumiera_config_lookup_item_find (LumieraConfigLookup self, const char* key); /** - * Find a the bottommost config item stored to a given key. + * Find a the bottom most config item stored to a given key. * defaults sits at the bottom if exists * @param self lookup structure where the key shall be searched * @param key string to be looked up - * @return TODO */ LumieraConfigitem lumiera_config_lookup_item_tail_find (LumieraConfigLookup self, const char* key); -/* - Lookup hash entries for the cuckoo hash -*/ +/* Lookup hash entries for the cuckoo hash */ -/** - * Structure defining single hash table entries. - * @internal - */ + +/** @internal Structure defining single hash table entries.*/ struct lumiera_config_lookupentry_struct { psplaynode node; - /* stack of all configitems stored under this key */ + + /** stack of all configitems stored under this key */ llist configitems; - /* - we store a copy of the full key here - configentry keys are complete as expected - section keys are the prefix stored with a trailing dot, - suffixes will be found by iterative search - */ + /** + * we store a copy of the full key here + * configentry keys are complete as expected + * section keys are the prefix stored with a trailing dot, + * suffixes will be found by iterative search + */ char* full_key; }; @@ -182,7 +178,8 @@ lumiera_config_lookupentry_destroy (LumieraConfigLookupentry self); void lumiera_config_lookupentry_delete (LumieraConfigLookupentry self); -#endif + +#endif /*COMMON_CONFIG_LOOKUP_H*/ /* // Local Variables: // mode: C diff --git a/src/common/config-typed.c b/src/common/config-typed.c index e7cc98ef6..cbfd88c49 100644 --- a/src/common/config-typed.c +++ b/src/common/config-typed.c @@ -1,5 +1,5 @@ /* - config-typed - Lumiera configuration highlevel interface + Config-typed - Lumiera configuration high-level interface Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,27 +17,27 @@ 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. -*/ -//TODO: Support library includes// +* *****************************************************/ + + +/** @file config-type.d + ** Implementation: high level typed configuration interfaces. + ** @note unfinished draft from 2008 + */ + #include "include/logging.h" #include "lib/tmpbuf.h" - - -//TODO: Lumiera header includes// #include "common/config.h" -//TODO: internal/static forward declarations// +#include + + + extern LumieraConfig lumiera_global_config; -//TODO: System includes// -#include -/** - * @file - * Here are the high level typed configuration interfaces defined. - */ const char* lumiera_config_link_get (const char* key, const char** value) @@ -176,7 +176,7 @@ scan_string (const char* in) *wpos = '\0'; } else - /* quotes doesnt match */ + /* quotes doesn't match */ LUMIERA_ERROR_SET (config, CONFIG_SYNTAX_VALUE, "unmatched quotes"); } else @@ -281,13 +281,10 @@ lumiera_config_wordlist_set (const char* key, const char** value) } -/** - * Word - * A single word, no quotes, chopped - */ /** * helper function, takes a raw input string and give a tmpbuf with the word parsed back. + * @remarks 'Word' is a single word, no quotes, chopped */ static char* scan_word (const char* in) diff --git a/src/common/config-wordlist.c b/src/common/config-wordlist.c index ef4942c8f..245119686 100644 --- a/src/common/config-wordlist.c +++ b/src/common/config-wordlist.c @@ -1,5 +1,5 @@ /* - config-wordlist - Lumiera wordlist access functions + Config-wordlist - Lumiera wordlist access functions Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,9 @@ 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. -*/ + +* *****************************************************/ + #include "include/logging.h" #include "lib/error.h" diff --git a/src/common/config.c b/src/common/config.c index bc39acb81..15601eaf5 100644 --- a/src/common/config.c +++ b/src/common/config.c @@ -1,5 +1,5 @@ /* - config.c - Lumiera configuration system + Config - Lumiera configuration system Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,30 +17,19 @@ 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. -*/ -//TODO: Support library includes// +* *****************************************************/ + + #include "include/logging.h" #include "lib/safeclib.h" #include "lib/tmpbuf.h" #include "common/config.h" - -//TODO: Lumiera header includes// - -//TODO: internal/static forward declarations// - - -//TODO: System includes// #include #include #include -/** - * @file - * - */ - LUMIERA_ERROR_DEFINE (CONFIG_SYNTAX, "syntax error in configfile"); LUMIERA_ERROR_DEFINE (CONFIG_SYNTAX_KEY, "syntax error in key"); @@ -90,7 +79,7 @@ int lumiera_config_init (const char* path) { TRACE (config_dbg); - REQUIRE (!lumiera_global_config, "Configuration subsystem already initialized"); + REQUIRE (!lumiera_global_config, "Configuration subsystem already initialised"); REQUIRE (path); @@ -240,7 +229,7 @@ lumiera_config_set (const char* key, const char* delim_value) LumieraConfigitem item = lumiera_config_lookup_item_find (&lumiera_global_config->keys, key); if (item && item->parent != &lumiera_global_config->defaults) { - TODO ("is a user writeable file?"); + TODO ("is a user writable file?"); TODO (" replace delim_value"); lumiera_configitem_set_value (item, delim_value); } @@ -262,7 +251,7 @@ lumiera_config_set (const char* key, const char* delim_value) ENSURE (*item->delim == '=' || *item->delim == '<', "syntax error,"); TODO ("insert in proper parent (file)"); - llist_insert_tail (&lumiera_global_config->TODO_unknown.childs, &item->link); + llist_insert_tail (&lumiera_global_config->TODO_unknown.children, &item->link); item->parent = &lumiera_global_config->TODO_unknown; lumiera_config_lookup_insert (&lumiera_global_config->keys, item); @@ -300,7 +289,7 @@ lumiera_config_setdefault (const char* line) ENSURE (*item->delim == '=' || *item->delim == '<', "default must be a configentry with key=value or keyline); - llist_insert_head (&lumiera_global_config->defaults.childs, &item->link); + llist_insert_head (&lumiera_global_config->defaults.children, &item->link); item->parent = &lumiera_global_config->defaults; lumiera_config_lookup_insert (&lumiera_global_config->keys, item); @@ -317,7 +306,7 @@ lumiera_config_dump (FILE* out) { fprintf (out, "# registered defaults:\n"); - LLIST_FOREACH (&lumiera_global_config->defaults.childs, node) + LLIST_FOREACH (&lumiera_global_config->defaults.children, node) fprintf (out, "%s\n", ((LumieraConfigitem) node)->line); fprintf (out, "# end of defaults\n\n"); diff --git a/src/common/config.h b/src/common/config.h index 48ac51a4b..0c08eb49e 100644 --- a/src/common/config.h +++ b/src/common/config.h @@ -1,5 +1,5 @@ /* - config.h - Lumiera configuration system + CONFIG.h - Lumiera configuration system Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,31 +17,36 @@ 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. + */ -#ifndef LUMIERA_CONFIG_H -#define LUMIERA_CONFIG_H -//TODO: Support library includes// +/** @file config.h + ** Interface for a lumiera configuration system (draft). + ** This configuration uses ini-style configuration files and supports some + ** simple types. A mechanism for overlay / cascading was planned. After some + ** debate it turned out that we had no clear vision regarding the scope of + ** that effort: should this system also manage (layered) defaults? should + ** it also be able to save user preferences? Anyway, development in that + ** area stalled and never reached the level of just loading and parsing + ** a simple file -- yet this was not considered a roadblock and we agreed + ** to revisit the topic when we've gained a better understanding of + ** session storage and management of default values and user preferences. + ** + ** @see lumiera::BasicSetup simple start-up configuration + ** @see http://lumiera.org/documentation/technical/backend/ConfigLoader.html ConfigLoader draft from 2008 + */ + +#ifndef COMMON_CONFIG_H +#define COMMON_CONFIG_H + #include "lib/error.h" #include "lib/mutex.h" +#include "common/config-lookup.h" +#include "common/configitem.h" -//TODO: Forward declarations// -struct lumiera_config_struct; - - -/* master config subsystem debug flag */ -//NOBUG_DECLARE_FLAG (config_all); -/* config subsystem internals */ -//NOBUG_DECLARE_FLAG (configsys); -/* high level typed interface operations */ -//NOBUG_DECLARE_FLAG (config_typed); -/* file operations */ -//NOBUG_DECLARE_FLAG (config_file); -/* single config items */ -//NOBUG_DECLARE_FLAG (config_item); -/* lookup config keys */ -//NOBUG_DECLARE_FLAG (config_lookup); +#include +#include LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX); @@ -49,23 +54,11 @@ LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX_KEY); LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX_VALUE); LUMIERA_ERROR_DECLARE (CONFIG_NO_ENTRY); - -//TODO: Lumiera header includes// -#include "common/config-lookup.h" -#include "common/configitem.h" - -//TODO: System includes// -#include -#include - -/** - * @file - * TODO documentation, http://www.pipapo.org/pipawiki/Lumiera/ConfigLoader - */ - #define LUMIERA_CONFIG_KEY_CHARS "abcdefghijklmnopqrstuvwxyz0123456789_." #define LUMIERA_CONFIG_ENV_CHARS "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789__" + + struct lumiera_config_struct { lumiera_config_lookup keys; @@ -198,12 +191,12 @@ lumiera_config_setdefault (const char* line); // * {{{int lumiera_config_TYPE_get(const char* key, TYPE* value, const char* default) }}} // High level config interface for different types. -// if default is given (!NULL) then value is set to default in case key was not found or any other error occured. +// if default is given (!NULL) then value is set to default in case key was not found or any other error occurred. // error code is still set and -1 (fail) is returned in case of an error, but it might be cleared with no ill effects. // NOTE: errors are persistent in our error handler, they must still be cleared, even when ignored. // if default is given then 'KEY_NOT_FOUND' is not a error here, if default is NULL then it is // NOTE2: default values are given as strings, the config loader remembers a given default value and checks if it got changed -// when it is _set(). Thus a default value can be supressed when set/written +// when it is _set(). Thus a default value can be suppressed when set/written /** * */ @@ -260,7 +253,7 @@ lumiera_config_wordlist_replace (const char* key, const char* value, const char* /** - * Add a word to the end of a wordlist if it doesnt exist already + * Add a word to the end of a wordlist if it doesn't exist already * @param key key under which this wordlist is stored * @param value new word to add * @param delims a string literal listing all characters which are treated as delimiters @@ -298,7 +291,7 @@ lumiera_config_reset (const char* key); int lumiera_config_info (const char* key, const char** filename, unsigned* line); -#endif +#endif /*COMMON_CONFIG_H*/ /* // Local Variables: // mode: C diff --git a/src/common/configentry.c b/src/common/configentry.c index 5ee5f35ae..11437ccf9 100644 --- a/src/common/configentry.c +++ b/src/common/configentry.c @@ -1,5 +1,5 @@ /* - configentry.c - single entries from configfiles + Configentry - single entries from configfiles Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,26 +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. -*/ -//TODO: Support library includes// +* *****************************************************/ + + #include "lib/safeclib.h" - -//TODO: Lumiera header includes// #include "common/configentry.h" -//TODO: internal/static forward declarations// -//TODO: System includes// - - -/** - * @file - * - */ - -//code goes here// LumieraConfigitem lumiera_configentry_new (LumieraConfigitem tmp) { @@ -65,10 +54,3 @@ struct lumiera_configitem_vtable lumiera_configentry_funcs = -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ diff --git a/src/common/configentry.h b/src/common/configentry.h index c2c1eadd8..58ea04691 100644 --- a/src/common/configentry.h +++ b/src/common/configentry.h @@ -1,5 +1,5 @@ /* - configentry.h - single entries from configfiles + CONFIGENTRY.h - single entries from configfiles Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,31 +17,23 @@ 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. + */ -#ifndef LUMIERA_CONFIGENTRY_H -#define LUMIERA_CONFIGENTRY_H -//TODO: Support library includes// +#ifndef COMMON_CONFIGENTRY_H +#define COMMON_CONFIGENTRY_H + +#include "common/configitem.h" + +#include + -//TODO: Forward declarations// typedef struct lumiera_configentry_struct lumiera_configentry; typedef lumiera_configentry* LumieraConfigentry; -//TODO: Lumiera header includes// -#include "common/configitem.h" - -//TODO: System includes// -#include - - -/** - * @file - */ - -//TODO: declarations go here// struct lumiera_configentry_struct { lumiera_configitem entry; @@ -57,7 +49,7 @@ lumiera_configentry_new (LumieraConfigitem tmp); LumieraConfigitem lumiera_configentry_destroy (LumieraConfigitem self); -#endif +#endif /*COMMON_CONFIGENTRY_H*/ /* // Local Variables: // mode: C diff --git a/src/common/configitem.c b/src/common/configitem.c index de290e16a..01850af4d 100644 --- a/src/common/configitem.c +++ b/src/common/configitem.c @@ -1,5 +1,5 @@ /* - configitem.c - generalized hierachy of configuration items + Configitem - generalised hierarchy of configuration items Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -22,8 +22,7 @@ /** @file configitem.c - ** create a configitem out of a single line. - ** + ** Implementation: create a configitem from a single line of the config file. */ @@ -32,12 +31,13 @@ #include "lib/safeclib.h" #include "lib/tmpbuf.h" - -//TODO: Lumiera header includes// #include "common/config.h" #include "common/configitem.h" #include "common/configentry.h" +#include +#include + static LumieraConfigitem parse_directive (LumieraConfigitem self, char* itr); @@ -46,8 +46,6 @@ static LumieraConfigitem parse_section (LumieraConfigitem self, char* itr); static LumieraConfigitem parse_configentry (LumieraConfigitem self, char* itr); -#include -#include @@ -59,7 +57,7 @@ lumiera_configitem_init (LumieraConfigitem self) llist_init (&self->link); self->parent = NULL; - llist_init (&self->childs); + llist_init (&self->children); llist_init (&self->lookup); @@ -81,10 +79,10 @@ lumiera_configitem_destroy (LumieraConfigitem self, LumieraConfigLookup lookup) if (self) { - LLIST_WHILE_HEAD (&self->childs, node) + LLIST_WHILE_HEAD (&self->children, node) lumiera_configitem_delete ((LumieraConfigitem) node, lookup); - ENSURE (llist_is_empty (&self->childs), "destructor didn't remove childs"); + ENSURE (llist_is_empty (&self->children), "destructor didn't remove children"); if (self->vtable && self->vtable->destroy) self->vtable->destroy (self); @@ -151,8 +149,8 @@ lumiera_configitem_move (LumieraConfigitem self, LumieraConfigitem source) self->parent = source->parent; - llist_init (&self->childs); - llist_insertlist_next (&self->childs, &source->childs); + llist_init (&self->children); + llist_insertlist_next (&self->children, &source->children); llist_init (&self->lookup); llist_insertlist_next (&self->lookup, &source->lookup); diff --git a/src/common/configitem.h b/src/common/configitem.h index 92d12a6c2..3781dbcd6 100644 --- a/src/common/configitem.h +++ b/src/common/configitem.h @@ -1,5 +1,5 @@ /* - configitem.h - generalized hierarchy of configuration items + CONFIGITEM.h - generalised hierarchy of configuration items Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,76 +17,53 @@ 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. + */ -#ifndef LUMIERA_CONFIGITEM_H -#define LUMIERA_CONFIGITEM_H -//TODO: Support library includes// +/** @file configitem.h + ** Hierarchy of configuration items. + ** configitems form a 3 level hierarchy: + ** + ** \verbatim + ** 1. file: + ** contain sections + ** + ** 2. section: + ** [prefix suffix] + ** contain lines + ** + ** 3. lines are + ** comment: + ** empty line or line only containing spaces and tabs + ** line starting with spaces and tabs followed by a # + ** directive: + ** '@include name' or '@readonly' + ** directives are only valid at the toplevel section [] + ** configurationentry: + ** 'key = value' or 'key < redirect' + ** erroneous: + ** any line which can't be parsed + ** \endverbatim + */ + +#ifndef COMMON_CONFIGITEM_H +#define COMMON_CONFIGITEM_H + + #include "lib/llist.h" - -//TODO: Forward declarations// +/* Forward declarations */ typedef struct lumiera_configitem_struct lumiera_configitem; typedef lumiera_configitem* LumieraConfigitem; struct lumiera_configitem_vtable; -//TODO: Lumiera header includes// #include "common/config-lookup.h" - -//TODO: System includes// #include -/** - * @file - * configitems build a 3 level hierarchy: - * - * 1. file: - * contain sections - * - * 2. section: - * [prefix suffix] - * contain lines - * - * 3. lines are - * comment: - * empty line or line only containing spaces and tabs - * line starting with spaces and tabs followed by a # - * directive: - * '@include name' or '@readonly' - * directives are only valid at the toplevel section [] - * configurationentry: - * 'key = value' or 'key < redirect' - */ - - -//TODO: declarations go here// -/** - * @file - * configitems build a 3 level hierarchy: - * - * 1. file: - * contain sections - * - * 2. section: - * [prefix suffix] - * contain lines - * - * 3. lines are - * comment: - * empty line or line only containing spaces and tabs - * line starting with spaces and tabs followed by a # - * directive: - * '@include name' or '@readonly' - * directives are only valid at the toplevel section [] - * configurationentry: - * 'key = value' or 'key < redirect' - * erroneous: - * any line which cant be parsed - */ struct lumiera_configitem_vtable { @@ -96,9 +73,9 @@ struct lumiera_configitem_vtable struct lumiera_configitem_struct { - llist link; // all lines on the same hierarchy level are linked here (see childs) + llist link; // all lines on the same hierarchy level are linked here (see children) LumieraConfigitem parent; // parent section - llist childs; // root node for all lines below this hierarchy + llist children; // root node for all lines below this hierarchy llist lookup; // all lines with the same key are stacked up on the lookup @@ -109,6 +86,7 @@ struct lumiera_configitem_struct struct lumiera_configitem_vtable* vtable; // functiontable for subclassing }; + LumieraConfigitem lumiera_configitem_init (LumieraConfigitem self); @@ -130,7 +108,8 @@ lumiera_configitem_parse (LumieraConfigitem self, const char* line); LumieraConfigitem lumiera_configitem_move (LumieraConfigitem self, LumieraConfigitem dest); -#endif + +#endif /*COMMON_CONFIGITEM_H*/ /* // Local Variables: // mode: C diff --git a/src/common/interface-descriptor.h b/src/common/interface-descriptor.h index d278562e2..7be369a17 100644 --- a/src/common/interface-descriptor.h +++ b/src/common/interface-descriptor.h @@ -17,16 +17,19 @@ 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. + */ -#ifndef LUMIERA_INTERFACEDESCRIPTOR_H -#define LUMIERA_INTERFACEDESCRIPTOR_H + + +#ifndef COMMON_INTERFACEDESCRIPTOR_H +#define COMMON_INTERFACEDESCRIPTOR_H #include "common/interface.h" /** * Release state of an interface implementation. - * The interface subsystem must be able to categorize implementations to present possible + * The interface subsystem must be able to categorise implementations to present possible * upgrade paths to the user. This is done by the tagging it to a certain state in concert * with the version and the user supplied version compare function. The respective numbers * are chosen in a way that a higher value indicates precedence when selecting an implementation. @@ -73,7 +76,7 @@ LUMIERA_INTERFACE_DECLARE (lumieraorg_interfacedescriptor, 0, #if 0 /** - * For convenience, a copy'n'paste descriptor + * For convenience: a copy'n'paste descriptor */ LUMIERA_INTERFACE_INSTANCE (lumieraorg_interfacedescriptor, 0, /*IDENTIFIER*/, @@ -131,7 +134,7 @@ LUMIERA_INTERFACE_INSTANCE (lumieraorg_interfacedescriptor, 0, #endif -#endif /* LUMIERA_INTERFACEDESCRIPTORS_H */ +#endif /* COMMON_INTERFACEDESCRIPTOR_H */ /* // Local Variables: // mode: C diff --git a/src/common/interface.c b/src/common/interface.c index 865ef86dd..51cd897ef 100644 --- a/src/common/interface.c +++ b/src/common/interface.c @@ -1,5 +1,5 @@ /* - interface.c - Lumiera interface api + Interface - Lumiera interface handling Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +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 interface.c + ** Implementation: handling of interfaces (extension points). + ** From a programmers perspective interfaces only need to be opened when needed and closed + ** when finished with them. There is no difference if the interface is internally provided + ** by the core or provided by an external plugin. + ** Interfaces can be opened multiple times and cross reference each other. + */ + #include "include/logging.h" @@ -31,15 +42,9 @@ #include -/** - * @file - * From a programmers perspective interfaces only need to be opened when needed and closed - * when finished with them. There is no difference if the interface is internally provided - * by the core or provided by an external plugin. - * Interfaces can be opened multiple times and cross reference each other. - */ -/* the mother of all interfaces */ + +/** the mother of all interfaces */ LumieraInterface lumiera_interface_interface; static LumieraInterfacenode @@ -85,10 +90,10 @@ lumiera_interface_open (const char* interface, unsigned version, size_t minminor static void push_dependency (LumieraInterfacenode parent, LumieraInterfacenode child) { - /* push a dependency on the dependency array, allcoate or resize it on demand */ + /* push a dependency on the dependency array, allocate or resize it on demand */ TRACE (interface_dbg, "%s %s", parent->interface->name, child->interface->name); - /* no dependencies recorded yet, alloc a first block for 4 pointers */ + /* no dependencies recorded yet, allocate a first block for 4 pointers */ if (!parent->deps_size) parent->deps = lumiera_calloc (parent->deps_size = 4, sizeof (LumieraInterfacenode)); @@ -161,7 +166,7 @@ lumiera_interface_open_interfacenode (LumieraInterfacenode self) static LumieraInterfacenode stack = NULL; /* - Ok, this got little more complicated than it should be, + OK, this got little more complicated than it should be, but finally it handles any kind of cross dependencies between interfaces gracefully */ @@ -306,7 +311,7 @@ lumiera_interfacenode_close (LumieraInterfacenode self) } /** - * Definitinon of 'the mother of all interfaces' + * Definition of 'the mother of all interfaces' * since this interface is singleton and required for any component to open any other * interface this should get a very stable interface and likely never change. */ diff --git a/src/common/interface.h b/src/common/interface.h index 08d2c86fa..060749d11 100644 --- a/src/common/interface.h +++ b/src/common/interface.h @@ -1,5 +1,5 @@ /* - interface.h - Lumiera interface macros and structures + INTERFACE.h - Lumiera interface macros and structures Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,89 +17,81 @@ 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 interface.h + ** @brief Lumiera interface macros and structures. + ** + ** Lumiera uses a system of versioned interfaces as external extension points + ** and for defining plug-ins. The interfaces defined here are C compatible and, + ** thus, can be used by any language able to bind to C. The interfaces are + ** versioned to provide forward and backward compatibility for both source and + ** binary deployment of modules. + ** + ** \par Overview + ** + ** To make an interface available to code so that the code can use the + ** interface, the interface needs to be declared and then defined. We provide a + ** number of macros here which ease this process. + ** + ** The interface is declared by placing the following macro in a + ** header file: + ** \code + ** LUMIERA_INTERFACE_DECLARE(name, version, + ** LUMIERA_INTERFACE_SLOT(ret, name, params), + ** ... + ** ) + ** + ** \endcode + ** Any code that wants to use this interface must then include the header file. + ** + ** The interface is defined by mapping interface functions to slots, or + ** providing inline definitions for slot functions. Defining the interface has + ** the following form: + ** \code + ** LUMIERA_INTERFACE_INSTANCE(iname, version, name, descriptor, acquire, release, + ** LUMIERA_INTERFACE_MAP (slot, function), + ** LUMIERA_INTERFACE_INLINE (slot, ret, params, {body}), + ** ... + ** ) + ** \endcode + ** + ** A collection of interfaces can be defined in 2 different ways depending on + ** where whether the interface is exported by the core, or by a plugin: + ** \code + ** LUMIERA_EXPORT(queryfunc, + ** LUMIERA_INTERFACE_DEFINE(...), + ** ... + ** ) // Exporting from the core + ** + ** LUMIERA_PLUGIN(descriptor, acquire, release, + ** LUMIERA_INTERFACE_DEFINE(...), + ** ... + ** ) // Exporting from an interface + ** \endcode + ** + ** \par Naming and Versioning + ** + ** Interfaces have unique names and a major and minor version. The name and the major version + ** is used to construct a C identifier for the interface, the minor version is implicitly defined + ** by the number of functions in the interface. Interface instances are not versioned by the + ** interface system, versioning these will be defined somewhere else. + ** + ** Slot names are normal C identifiers, how these shall be versioned has to be defined somewhere + ** else and is not the subject of the interface system. Each function can have its own unique UUID. + */ + #ifndef LUMIERA_INTERFACE_H #define LUMIERA_INTERFACE_H #include "lib/ppmpl.h" #include "lib/psplay.h" -/* TODO better doxygen formating */ - -/** - * @file interface.h - * @brief Lumiera interface macros and structures. - * - * Lumiera uses a system of versioned interfaces instead of just employing a - * simple library (containg the functions and data) and header file strategy. - * The interfaces defined here are C compatible and, thus, can be used by any - * language able to bind to C. The interfaces are versioned to provide forward - * and backward compatibility for both source and binary deployment of - * modules. The interfaces play a central role in the Lumiera architecture. - * Other facilities, such as serializing sessions and distributed computing - * will use them extensively. - * - * Overview - * - * Interfaces are used for 2 reasons in Lumiera: - * -# The Lumiera core system uses them internally and exports its functionality though them. - * -# Plugins (effects, ...) extend Lumiera by providing interfaces - * - * To make an interface available to code so that the code can use the - * interface, the interface needs to be declared and then defined. We provide a - * number of macros here which ease this process. - * - * The interface is declared by placing the following macro in a - * header file: - * \code - * LUMIERA_INTERFACE_DECLARE(name, version, - * LUMIERA_INTERFACE_SLOT(ret, name, params), - * ... - * ) - * - * \endcode - * Any code that wants to use this interface must then include the header file. - * - * The interface is defined by mapping interface functions to slots, or - * providing inline definitions for slot functions. Defining the interface has - * the following form: - * \code - * LUMIERA_INTERFACE_INSTANCE(iname, version, name, descriptor, acquire, release, - * LUMIERA_INTERFACE_MAP (slot, function), - * LUMIERA_INTERFACE_INLINE (slot, ret, params, {body}), - * ... - * ) - * \endcode - * - * A collection of interfaces can be defined in 2 different ways depending on - * where whether the interface is exported by the core, or by a plugin: - * \code - * LUMIERA_EXPORT(queryfunc, - * LUMIERA_INTERFACE_DEFINE(...), - * ... - * ) // Exporting from the core - * - * LUMIERA_PLUGIN(descriptor, acquire, release, - * LUMIERA_INTERFACE_DEFINE(...), - * ... - * ) // Exporting from an interface - * \endcode - * - * Naming and Versioning - * - * Interfaces have unique names and a major and minor version. The name and the major version - * is used to construct a C identifier for the interface, the minor version is implicitly defined - * by the number of functions in the interface. Interface instances are not versioned by the - * interface system, versioning these wii be defined somewhere else. - * - * Slot names are normal C identifiers, how these shall be versioned has to be defined somewhere - * else and is not the subject of the interface system. Each function can have its own unique uuid. - */ -/* - Macros to Declare an Interface - */ +/* ==== Macros to Declare an Interface */ /** * @@ -179,7 +171,7 @@ LUMIERA_INTERFACE_TYPE(name, version) \ * Declare a function slot inside an interface. * @param ret return type of the function * @param name name of this slot - * @param params parentized list of parameters for the function + * @param params parenthesised list of parameters for the function */ #define PPMPL_FOREACH_LUMIERA_INTERFACE_SLOT(ret, name, params) \ ret (*name) params; \ @@ -240,7 +232,7 @@ PPMPL_FOREACH(_P2_, __VA_ARGS__) * Map a inline defined function to a interface slot * @param slot name of the slot to be mapped * @param ret return type of the inline function - * @param params parentized list of parameters given to the function + * @param params parenthesised list of parameters given to the function * @param ... braced function body * * @note C++ requires that all mappings are in the same order than defined in the interface declaration, diff --git a/src/common/interfaceregistry.c b/src/common/interfaceregistry.c index 75e05c17b..37f3ee4ff 100644 --- a/src/common/interfaceregistry.c +++ b/src/common/interfaceregistry.c @@ -1,5 +1,5 @@ /* - interfaceregistry.c - Lumiera interface registry + InterfaceRegistry - registry for extension points Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,27 +17,26 @@ 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 interfaceregistry.c + ** Interface instances are published and activated by registering them + ** into a global registry, which is defined here. This instances are identified + ** by their name and major version. + */ #include "include/logging.h" #include "lib/error.h" #include "lib/psplay.h" #include "lib/safeclib.h" - #include - - #include "common/plugin.h" #include "common/interfaceregistry.h" -/** - * @file - * Interface instances are published and activated by registering them - * into a global registry, which is defined here. This instances are identified - * by their name and major version. - */ PSplay lumiera_interfaceregistry; @@ -81,9 +80,7 @@ lumiera_interfacenode_delete (LumieraInterfacenode self) } -/** - * Initialize the interface registry - */ +/** Initialise the interface registry */ void lumiera_interfaceregistry_init (void) { diff --git a/src/common/interfaceregistry.h b/src/common/interfaceregistry.h index 677ef6c89..3c305353f 100644 --- a/src/common/interfaceregistry.h +++ b/src/common/interfaceregistry.h @@ -1,5 +1,5 @@ /* - interfaceregistry.h - Lumiera interface registry + INTERFACEREGISTRY.h - Lumiera interface registry Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,17 @@ 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 interfaceregistry.h + ** Global registry for interfaces (extension points). + ** Interface instances are published and activated by registering them + ** into a global registry, which is defined here. This instances are identified + ** by their name and major version. + */ + #ifndef LUMIERA_INTERFACEREGISTRY_H #define LUMIERA_INTERFACEREGISTRY_H @@ -31,17 +41,6 @@ #include -/** - * @file - * Interface instances are published and activated by registering them - * into a global registry, which is defined here. This instances are identified - * by their name and major version. - */ - -//NOBUG_DECLARE_FLAG (interface_all); -//NOBUG_DECLARE_FLAG (interfaceregistry); -//NOBUG_DECLARE_FLAG (interface); - extern PSplay lumiera_interfaceregistry; extern lumiera_recmutex lumiera_interface_mutex; @@ -70,15 +69,17 @@ struct lumiera_interfacenode_struct /** temporary used to stack interfaces when recursively opening/closing them */ LumieraInterfacenode lnk; - /** allocated size of the following deps table */ + + /** allocated size of the following dependency table */ size_t deps_size; - /** NULL terminated table of all dependencies (interfaces opened on initialization) */ + + /** NULL terminated table of all dependencies (interfaces opened on initialisation) */ LumieraInterfacenode* deps; }; /** - * Initialize the interface registry + * Initialise the interface registry */ void lumiera_interfaceregistry_init (void); diff --git a/src/common/plugin-dynlib.c b/src/common/plugin-dynlib.c index 3cac19af2..dcfd96fdd 100644 --- a/src/common/plugin-dynlib.c +++ b/src/common/plugin-dynlib.c @@ -1,5 +1,5 @@ /* - plugin-dynlib - Lumiera Plugin loader for dynamic libraries + PluginDynlib - Lumiera Plugin loader for dynamic libraries Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,13 @@ 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 plugin-dynlib.c + ** Implementation of plugin loader for dynamic libraries. + */ #include "include/logging.h" #include "lib/tmpbuf.h" @@ -26,10 +32,6 @@ #include #include -/** - * @file - * Plugin loader for dynamic libraries. - */ LumieraPlugin lumiera_plugin_load_DYNLIB (const char* name) diff --git a/src/common/plugin.c b/src/common/plugin.c index a44592dc8..12aaa6f8f 100644 --- a/src/common/plugin.c +++ b/src/common/plugin.c @@ -1,5 +1,5 @@ /* - plugin.c - Lumiera Plugin loader + Plugin - Lumiera Plugin loader implementation Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,7 +17,8 @@ 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 plugin.c @@ -250,7 +251,7 @@ lumiera_plugin_load (const char* plugin) { TRACE (pluginloader_dbg, "plugin=%s", plugin); - /* dispatch on ext, call the registered function */ + /* dispatch on extension, call the registered function */ const char* ext = strrchr (plugin, '.'); LumieraPlugintype itr = lumiera_plugin_types; @@ -312,7 +313,7 @@ lumiera_plugin_unload (LumieraPlugin self) if (self->refcnt) return self->refcnt; - /* dispatch on ext, call the registered function */ + /* dispatch on extension, call the registered function */ const char* ext = strrchr (self->name, '.'); LumieraPlugintype itr = lumiera_plugin_types; diff --git a/src/common/plugin.h b/src/common/plugin.h index bd77b3806..a5df05ab2 100644 --- a/src/common/plugin.h +++ b/src/common/plugin.h @@ -1,5 +1,5 @@ /* - plugin.h - Plugin loader + PLUGIN.h - Plugin loader Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -17,9 +17,38 @@ 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. + */ -#ifndef LUMIERA_PLUGIN_H -#define LUMIERA_PLUGIN_H + + +/** @file plugin.h + ** Lumiera plugins define 'interfaces' as shown in interface.h, the plugin system handles the loading + ** of all kinds of plugins under the hood, invoked from the interface system. Most things defined here + ** are called internally and should not be used by other parts of the application. + ** + ** \par Plugin discovery + ** The #lumiera_plugin_discover() function offers a automatic way to load and register new plugins. It + ** traverses all configured plugin directories. It takes to function for loading and registering plugins + ** as parameter, by now this only uses the here defined \c plugin_load() and \c plugin_register() functions + ** which lets it load any newly found plugin unconditionally. Later these callbacks will be replaced by + ** a smarter system (plugindb) which makes it possible to load plugins on-demand and select proper + ** plugins based on their version and capabilities. + ** + ** \par Plugin loading + ** Plugins are loaded and initialised in a sequence of steps: + ** plugin_load() dispatches to a specific loader function depending on the type (extension) of a plugin. + ** This loader allocates a new plugin structure with plugin_new() and then does it work and eventually + ** finalising the plugin structure initialisation with plugin_init() by providing a handle to a + ** \c lumieraorg__plugin interface. plugin_init() also stores the current error state (which might be clean) + ** into the plugin. After that the plugin can be registered which records it in the plugin registry and if + ** its error state is clean, registering all interfaces it offers in the interface registry. With that + ** the plugin is ready to be used. Plugins with the error state set should still be registered to prevent + ** further discovery runs to try loading them again. + ** + */ + +#ifndef COMMON_PLUGIN_H +#define COMMON_PLUGIN_H #include "lib/psplay.h" #include "lib/error.h" @@ -29,33 +58,6 @@ #include #include -/** - * @file - * Lumiera plugins defines 'interfaces' as shown in interface.h, the plugin system handles the loading - * of all kinds of plugins under the hood, invoked from the interface system. Most things defined here - * are called internally and should not be used by other parts of the application. - * - * Plugin discovery - * The plugin_discover() function offers a automatic way to load and register new plugins. It traverses - * all configured plugin directories. It takes to function for loading and registering plugins as - * parameter, by now this only uses the here defined plugin_load() and plugin_register() functions - * which lets it load any newly found plugin unconditionally. Later these callbacks will be replaced by - * a smarter system (plugindb) which makes it possible to load plugins on-demand and select proper - * plugins based on their version and capabilities. - * - * Plugin loading - * Plugins are loaded and initialized in a sequence of steps: - * plugin_load() dispatches to a specific loader function depending on the type (extension) of a plugin. - * This loader allocates a new plugin structure with plugin_new() and then does it work and eventually - * finalizing the plugin structure initialization with plugin_init() by providing a handle to a - * lumieraorg__plugin interface. plugin_init() also stores the current error state (which might be clean) - * into the plugin. After that the plugin can be registered which records it in the pluginregistry and if - * its error state is clean, registering all interfaces it offers in the interface registry. With that - * the plugin is ready to be used. Plugins with the error state set should still be registered to prevent - * further discovery runs to try loading them again. - * - */ - LUMIERA_ERROR_DECLARE(PLUGIN_INIT); LUMIERA_ERROR_DECLARE(PLUGIN_OPEN); @@ -64,9 +66,6 @@ LUMIERA_ERROR_DECLARE(PLUGIN_REGISTER); LUMIERA_ERROR_DECLARE(PLUGIN_VERSION); -//NOBUG_DECLARE_FLAG (plugin); - -/* tool macros*/ struct lumiera_plugin_struct; @@ -75,22 +74,21 @@ typedef lumiera_plugin* LumieraPlugin; /** - * Allocates an preinitializes a plugin structure + * Allocates an preinitialises a plugin structure * @internal * @param name path/filename of the plugin - * @return new allocated/preinitialized plugin structure with its error state set to LUMIERA_ERROR_PLUGIN_INIT + * @return new allocated/preinitialised plugin structure with its error state set to \c LUMIERA_ERROR_PLUGIN_INIT */ LumieraPlugin lumiera_plugin_new (const char* name); /** - * Complete plugin initialization - * @internal + * @internal Complete plugin initialisation * Stores any pending error (from loading) in self which clears out the LUMIERA_ERROR_PLUGIN_INIT error state - * which was initialized by lumiera_plugin_new(), stores the handle and plugin pointers in the plugin struct. + * which was initialised by lumiera_plugin_new(), stores the handle and plugin pointers in the plugin struct. * @param self pointer to the plugin struct * @param handle opaque handle referring to some plugin type specific data - * @param plugin a lumieraorg__plugin interface which will be used to initialize this plugin + * @param plugin a lumieraorg__plugin interface which will be used to initialise this plugin */ LumieraPlugin lumiera_plugin_init (LumieraPlugin self, void* handle, LumieraInterface plugin); @@ -98,7 +96,7 @@ lumiera_plugin_init (LumieraPlugin self, void* handle, LumieraInterface plugin); /** * Tries to load a plugin - * Creates a new plugin structure and tries to load and initialize the plugin. + * Creates a new plugin structure and tries to load and initialise the plugin. * The plugins error state may be set on any problem which should be queried later. * @param plugin path/filename of the plugin to load * @return pointer to the new plugin structure (always, never NULL, check error state) @@ -109,12 +107,12 @@ lumiera_plugin_load (const char* plugin); /** * Register a plugin and its interfaces. - * Registers the plugin (unconditionally) at the pluginregistry. + * Registers the plugin (unconditionally) at the plugin registry. * When the error state of the plugin is NULL then use its lumieraorg__plugin interface * to register all interfaces offered by the plugin at the interface registry. * Registered plugins will be automatic unloaded at application end. * @param self the plugin to be registered (calling with NULL is a no-op) - * @return 1 on success (including calling with NULL) and 0 when a error occured + * @return 1 on success (including calling with NULL) and 0 when a error occurred */ int lumiera_plugin_register (LumieraPlugin self); @@ -139,7 +137,7 @@ lumiera_plugin_handle (LumieraPlugin self); /** * Query the plugin name - * The name is the path and filname under which it was loaded + * The name is the path and filename under which it was loaded * @param self plugin to query * @return pointer to the name string */ @@ -148,8 +146,7 @@ lumiera_plugin_name (LumieraPlugin self); /** - * Increment refcount - * @internal + * @internal Increment refcount * @param self plugin which refcount to increment */ void @@ -157,8 +154,7 @@ lumiera_plugin_refinc (LumieraPlugin self); /** - * Decrement refcount - * @internal + * @internal Decrement refcount * @param self plugin which refcount to decrement */ void @@ -195,7 +191,8 @@ lumiera_plugin_discover (LumieraPlugin (*callback_load)(const char* plugin), int (*callback_register) (LumieraPlugin)); -/* psplay support functions */ +/* === psplay support functions === */ + int lumiera_plugin_cmp_fn (const void* keya, const void* keyb); @@ -205,4 +202,6 @@ lumiera_plugin_key_fn (const PSplaynode node); void lumiera_plugin_delete_fn (PSplaynode node); -#endif /* LUMIERA_PLUGIN_H */ + + +#endif /*COMMON_PLUGIN_H*/ diff --git a/src/lib/condition.h b/src/lib/condition.h index 70d1a2a03..06e386813 100644 --- a/src/lib/condition.h +++ b/src/lib/condition.h @@ -165,7 +165,7 @@ typedef lumiera_condition* LumieraCondition; /** * Initialize a condition variable - * @param self is a pointer to the condition variable to be initialized + * @param self is a pointer to the condition variable to be initialised * @return self as given */ LumieraCondition diff --git a/src/lib/cuckoo.h b/src/lib/cuckoo.h index 9fc5c2e75..cb7abf371 100644 --- a/src/lib/cuckoo.h +++ b/src/lib/cuckoo.h @@ -75,7 +75,7 @@ typedef void (*cuckoo_movfunc)(void* dest, void* src, size_t size); /** - * Function table used to specialize various funtions used by the hash. + * Function table used to specialise various functions used by the hash. * TODO some elements might be NULL, then defaults are used */ struct cuckoo_vtable @@ -90,11 +90,11 @@ struct cuckoo_vtable /** - * Initialize a cuckoo hash. - * @param self pointer to a uninitialized cuckoo datastructure + * Initialise a cuckoo hash. + * @param self pointer to a uninitialised cuckoo datastructure * @param itemsize size for a single hash entry, will be rounded up to align CUCKOO_GRANULARITY - * @param vtable initialized vtable - * @return The initialized hashtable or NULL at allocation failure + * @param vtable initialised vtable + * @return The initialised hashtable or NULL at allocation failure */ Cuckoo cuckoo_init (Cuckoo self, size_t itemsize, struct cuckoo_vtable* vtable); @@ -103,8 +103,8 @@ cuckoo_init (Cuckoo self, size_t itemsize, struct cuckoo_vtable* vtable); * Allocate a new cuckoo hash. * @param itemsize size for a single hash entry, will be rounded up to align CUCKOO_GRANULARITY * @param startsize initial size of table t3, as 2's exponent - * @param vtable initialized vtable - * @return The initialized hashtable or NULL at allocation failure + * @param vtable initialised vtable + * @return The initialised hashtable or NULL at allocation failure */ Cuckoo cuckoo_new (size_t itemsize, struct cuckoo_vtable* vtable); @@ -114,7 +114,7 @@ cuckoo_new (size_t itemsize, struct cuckoo_vtable* vtable); * Destroy a cuckoo hash. * Frees internal used resources. * @param self cuckoo hash to destroy - * @return The now uninitialized hashtable + * @return The now uninitialised hashtable */ Cuckoo cuckoo_destroy (Cuckoo self); diff --git a/src/lib/llist.h b/src/lib/llist.h index d81b77c00..2d02ab21b 100644 --- a/src/lib/llist.h +++ b/src/lib/llist.h @@ -29,7 +29,7 @@ /** * @file * Intrusive cyclic double linked list - * There is only one node type which contains a forward and a backward pointer. In a empty initialized node, + * There is only one node type which contains a forward and a backward pointer. In a empty initialised node, * this pointers point to the node itself. Note that these pointers can never ever become NULL. * This lists are used by using one node as 'root' node where its both pointers are the head/tail pointer to the actual list. * Care needs to be taken to ensure not to apply any operations meant to be applied to data nodes to the root node. @@ -44,7 +44,7 @@ * #define LLIST_IMPLEMENTATION before including this header yields in definitions * this can be used to generate a library. This is currently untested and not recommended. * The rationale for using inlined functions is that most functions are very small and likely to be used in performance critical parts. - * Inlining can give a huge performance and optimization improvement here. + * Inlining can give a huge performance and optimisation improvement here. * The few functions which are slightly larger are expected to be the less common used ones, so inlining them too shouldn't be a problem either */ @@ -188,10 +188,10 @@ typedef llist ** LList_ref; tail = llist_tail (list)) /** - * Initialize a new llist. - * Must not be applied to a list node which is not empty! Lists need to be initialized + * Initialise a new llist. + * Must not be applied to a list node which is not empty! Lists need to be initialised * before any other operation on them is called. - * @param self node to be initialized + * @param self node to be initialised */ LLIST_FUNC (LList llist_init (LList self), return self->next = self->prev = self; diff --git a/src/lib/luid.h b/src/lib/luid.h index 3037f8f5d..020d0883e 100644 --- a/src/lib/luid.h +++ b/src/lib/luid.h @@ -60,8 +60,8 @@ /* - C++ can't initialize arrays from string literals with the trailing \0 cropped - C can't initialize non constant members, + C++ can't initialise arrays from string literals with the trailing \0 cropped + C can't initialise non constant members, there we go ////////////////////////////////TODO 3/2014 possibly not used anymore, after removing LUIDs from the Interface descriptors (see #925) */ diff --git a/src/lib/mpool.c b/src/lib/mpool.c index abcc8a810..724521c6f 100644 --- a/src/lib/mpool.c +++ b/src/lib/mpool.c @@ -43,7 +43,7 @@ void *(*mpool_malloc_hook)(size_t size) = malloc; void (*mpool_free_hook)(void *ptr) = free; -/** called after a mpool got initialized */ +/** called after a mpool got initialised */ void (*mpool_init_hook) (MPool self) = NULL; /** called before a mpool gets destroyed */ void (*mpool_destroy_hook) (MPool self) = NULL; @@ -196,7 +196,7 @@ mpool_cluster_alloc_ (MPool self) /* clear the bitmap */ memset (&cluster->data, 0, MPOOL_BITMAP_SIZE (self->elements_per_cluster)); - /* initialize freelist */ + /* initialise freelist */ for (unsigned i = 0; i < self->elements_per_cluster; ++i) { MPoolnode node = cluster_element_get (cluster, self, i); diff --git a/src/lib/mpool.h b/src/lib/mpool.h index 3d9ec4e13..b59ea2b58 100644 --- a/src/lib/mpool.h +++ b/src/lib/mpool.h @@ -86,23 +86,23 @@ struct mpool_struct extern void *(*mpool_malloc_hook)(size_t size); extern void (*mpool_free_hook)(void *ptr); -/** called after a mpool got initialized */ +/** called after a mpool got initialised */ 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()]:: initialize a new memory pool +//index.mpool_init xref:mpool_init[mpool_init()]:: Initialise a new memory pool //mpool [[mpool_init]] //mpool .mpool_init -//mpool Initialize a memory pool, memory pools must be initialized before being used. One can supply +//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 elemented are freed. +//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 initialized +//mpool pointer to the memory pool structure to be initialised //mpool `elem_size`:: //mpool size for a single element //mpool `elements_per_cluster`:: @@ -124,13 +124,13 @@ mpool_init (MPool self, size_t elem_size, unsigned elements_per_cluster, mpool_d //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 initialized and can be used again, this is some kindof +//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 initialized memory pool to be destroyed. +//mpool pointer to an initialised memory pool to be destroyed. //mpool return:: //mpool self //mpool diff --git a/src/lib/mrucache.h b/src/lib/mrucache.h index a96f02282..eeb871981 100644 --- a/src/lib/mrucache.h +++ b/src/lib/mrucache.h @@ -35,7 +35,7 @@ */ /** - * Callback function used to destruct/cleanup aged elements. + * Callback function used to destroy/cleanup aged elements. * shall clean the element sufficiently up to be ready for being freed or reused, * this callback function must be reentrant and prepared to be called twice. * @param node the llist node used to link cache elements (will be empty at call) @@ -53,9 +53,9 @@ typedef struct lumiera_mrucache_struct lumiera_mrucache; typedef lumiera_mrucache* LumieraMruCache; /** - * Initialize a cache. - * @param self cache to be initialized - * @param destructor_cb function for destructing a cache node, preparing for reuse. + * Initialise a cache. + * @param self cache to be initialised + * @param destructor_cb function for destroying a cache node, preparing for reuse. * @return self */ LumieraMruCache @@ -145,7 +145,7 @@ lumiera_mrucache_checkout (LumieraMruCache self, LList node) * This function is used to get a new element by deleting the oldest least used one from the cache. * The cache must be locked for this operation. * @param self cache - * @return pointer to the uninitialized memory ready for being reused or NULL when no element was available + * @return pointer to the uninitialised memory ready for being reused or NULL when no element was available */ static inline void* lumiera_mrucache_pop (LumieraMruCache self) diff --git a/src/lib/mutex.h b/src/lib/mutex.h index cfcba113d..cf51226b9 100644 --- a/src/lib/mutex.h +++ b/src/lib/mutex.h @@ -101,9 +101,9 @@ typedef lumiera_mutex* LumieraMutex; /** - * Initialize a mutex variable - * This initializes a 'fast' default mutex which must not be locked recursively from one thread. - * @param self is a pointer to the mutex to be initialized + * Initialise a mutex variable + * This initialises a 'fast' default mutex which must not be locked recursively from one thread. + * @param self is a pointer to the mutex to be initialised * @param purpose textual hint for the nobug resourcetracker * @param flag nobug logging target * @return self as given diff --git a/src/lib/psplay.h b/src/lib/psplay.h index 4858db8cd..f88ac8cb5 100644 --- a/src/lib/psplay.h +++ b/src/lib/psplay.h @@ -155,10 +155,10 @@ psplay_delete (PSplay self); /** - * Initialize a splay tree node + * Initialise a splay tree node * The user has to place this nodes within his datastructure and must - * initialize them before using them. - * @param self pointer to the node to be initialized + * Initialise them before using them. + * @param self pointer to the node to be initialised * @return self */ PSplaynode @@ -195,7 +195,7 @@ psplay_find (PSplay self, const void* key, int splayfactor); * @param self pointer to the splay tree * @param node node to be removed * @return pointer to the removed node - * removal is optimized for the case where one call it immediately after one did a + * removal is optimised for the case where one call it immediately after one did a * psplay_find() as last operation on that tree */ PSplaynode diff --git a/src/lib/reccondition.h b/src/lib/reccondition.h index a2a734a69..1a4b02828 100644 --- a/src/lib/reccondition.h +++ b/src/lib/reccondition.h @@ -165,8 +165,8 @@ typedef lumiera_reccondition* LumieraReccondition; /** - * Initialize a condition variable - * @param self is a pointer to the condition variable to be initialized + * Initialise a condition variable + * @param self is a pointer to the condition variable to be initialised * @return self as given */ LumieraReccondition diff --git a/src/lib/recmutex.h b/src/lib/recmutex.h index 0088b8ae6..229fbfa52 100644 --- a/src/lib/recmutex.h +++ b/src/lib/recmutex.h @@ -94,9 +94,9 @@ typedef struct lumiera_recmutex_struct lumiera_recmutex; typedef lumiera_recmutex* LumieraRecmutex; /** - * Initialize a recursive mutex variable - * Initializes a 'recursive' mutex which might be locked by the same thread multiple times. - * @param self is a pointer to the mutex to be initialized + * Initialise a recursive mutex variable + * Initialises a 'recursive' mutex which might be locked by the same thread multiple times. + * @param self is a pointer to the mutex to be initialised * @return self as given */ LumieraRecmutex diff --git a/src/lib/rwlock.h b/src/lib/rwlock.h index 9890cd1ef..41b2316af 100644 --- a/src/lib/rwlock.h +++ b/src/lib/rwlock.h @@ -142,7 +142,7 @@ typedef lumiera_rwlock* LumieraRWLock; /** * Initialize a rwlock - * @param self is a pointer to the rwlock to be initialized + * @param self is a pointer to the rwlock to be initialised * @return self as given */ LumieraRWLock @@ -153,7 +153,7 @@ lumiera_rwlock_init (LumieraRWLock self, /** * destroy a rwlock - * @param self is a pointer to the rwlock to be initialized + * @param self is a pointer to the rwlock to be initialised * @return self on success or NULL at error */ LumieraRWLock diff --git a/src/lib/safeclib.h b/src/lib/safeclib.h index 60ae3c5ad..c1fe79554 100644 --- a/src/lib/safeclib.h +++ b/src/lib/safeclib.h @@ -1,5 +1,5 @@ /* - safe_clib.h - Portable and safe wrapers around some clib functions and some tools + safe_clib.h - Portable and safe wrappers around some clib functions and some tools Copyright (C) CinelerraCV 2008, Christian Thaeter @@ -32,10 +32,10 @@ LUMIERA_ERROR_DECLARE(NO_MEMORY); /** * Install the resourcecollector run hook. * The resourcecollectr must be hooked into the safeclib at bootup after it got - * initialized and removed from it before shut down. Without resourcecollector + * initialised and removed from it before shut down. Without resourcecollector * failed allocations will abort(). * @param hook pointer to the resourcecollector_run function, must be of type - * lumiera_resourcecollector_run_fn but we dont want a dependency on backend in this header + * lumiera_resourcecollector_run_fn but we don't want a dependency on backend in this header */ void lumiera_safeclib_set_resourcecollector (void* hook); diff --git a/src/lib/slist.h b/src/lib/slist.h index 61fd9e10d..8dd89d5f3 100644 --- a/src/lib/slist.h +++ b/src/lib/slist.h @@ -30,13 +30,13 @@ * * List node is a structure, which consists only of a forward pointer. This is * much easier and makes code much cleaner, than to have forward pointer as is. - * In a empty initialized node, this pointer points to the node itself. Note + * In a empty initialised node, this pointer points to the node itself. Note * that this pointer can never ever become NULL. * * This lists are used by using one node as 'root' node where it's pointer is * the head pointer to the actual list. Care needs to be taken to ensure not to * apply any operations meant to be applied to data nodes to the root node. - * This way is the prefered way to use this lists. + * This way is the preferred way to use this lists. * * Alternatively one can store only a chain of data nodes and use a SList * pointer to point to the first item (which might be NULL in case no data is @@ -52,7 +52,7 @@ * 1 <= C <= N-1 nodes, and, thus, speed up search. * * This header can be used in 2 different ways: - * 1) (prerefered) just including it provides all functions as static inlined + * 1) (preferred) just including it provides all functions as static inlined * functions. This is the default * 2) #define LLIST_INTERFACE before including this header gives only the declarations * #define LLIST_IMPLEMENTATION before including this header yields in definitions @@ -60,7 +60,7 @@ * recommended. * The rationale for using inlined functions is that most functions are very * small and likely to be used in performance critical parts. Inlining can give - * a hughe performance and optimization improvement here. The few functions + * a huge performance and optimisation improvement here. The few functions * which are slightly larger are expected to be the less common used ones, so * inlining them too shouldn't be a problem either. */ @@ -184,11 +184,11 @@ typedef slist** SList_ref; for ( SList head = slist_head( list ); ! slist_is_empty( list ); head = slist_head( list ) ) /** - * Initialize a new llist. - * Must not be applied to a list node which is not empty! Lists need to be initialized + * Initialise a new llist. + * Must not be applied to a list node which is not empty! Lists need to be initialised * before any other operation on them is called. * - * @param list node to be initialized + * @param list node to be initialised */ SLIST_FUNC ( diff --git a/src/tool/alsa.c b/src/tool/alsa.c index d210693dd..68969f49a 100644 --- a/src/tool/alsa.c +++ b/src/tool/alsa.c @@ -35,7 +35,7 @@ static snd_pcm_sframes_t delay = 0; static unsigned int rate = 44100; -static int audio_initialized = 0; +static int audio_initialised = 0; size_t audio_offset() @@ -52,10 +52,10 @@ audio_init() const char* device; int err; - if(audio_initialized) + if(audio_initialised) return; - audio_initialized = 1; + audio_initialised = 1; device = getenv("ALSA_DEVICE"); @@ -104,7 +104,7 @@ audio_init() fprintf(stderr, "Buffer time is %.3f seconds\n", buffer_time / 1.0e6); if(0 > (err = snd_pcm_sw_params_current(playback_handle, sw_params))) - errx(EXIT_FAILURE, "Audio: Could not initialize software parameters: %s", + errx(EXIT_FAILURE, "Audio: Could not initialise software parameters: %s", snd_strerror(err)); snd_pcm_sw_params_set_start_threshold(playback_handle, sw_params, 0); diff --git a/tests/15mpool.tests b/tests/15mpool.tests index 487ccb7b3..c91fa671a 100644 --- a/tests/15mpool.tests +++ b/tests/15mpool.tests @@ -1,7 +1,7 @@ TESTING "Memory pool tests" ./test-mpool TEST "init/destroy" basic <