ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

merge doc fixes

Browse source 
Merge commit '163ba179ed93c49c6d331c16afe9e54e97ad1876'
This commit is contained in:
Fischlurch 2008-09-04 15:28:39 +02:00
commit d94f1b9305
13 changed files with 133 additions and 178 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
src/lib/condition.c
View file

@ -28,11 +28,7 @@
LUMIERA_ERROR_DEFINE (CONDITION_DESTROY, "condition destroy failed");
/**
* Initialize a condition variable
* @param self is a pointer to the condition variable to be initialized
* @return self as given
*/
LumieraCondition
lumiera_condition_init (LumieraCondition self)
{
@ -45,11 +41,6 @@ lumiera_condition_init (LumieraCondition self)
}
/**
* Destroy a condition variable
* @param self is a pointer to the condition variable to be destroyed
* @return self as given
*/
LumieraCondition
lumiera_condition_destroy (LumieraCondition self)
{

10
src/lib/condition.h
View file

@ -44,10 +44,20 @@ typedef struct lumiera_condition_struct lumiera_condition;
typedef lumiera_condition* LumieraCondition;
/**
* Initialize a condition variable
* @param self is a pointer to the condition variable to be initialized
* @return self as given
*/
LumieraCondition
lumiera_condition_init (LumieraCondition self);
/**
* Destroy a condition variable
* @param self is a pointer to the condition variable to be destroyed
* @return self as given
*/
LumieraCondition
lumiera_condition_destroy (LumieraCondition self);

14
src/lib/error.c
View file

@ -45,13 +45,7 @@ lumiera_error_tls_init (void)
pthread_key_create (&lumiera_error_tls, NULL);
}
/**
* Set error state for the current thread.
* If the error state of the current thread was cleared, then set it, else preserve the old state.
* @param nerr name of the error with 'LUMIERA_ERROR_' prefix (example: LUMIERA_ERROR_NO_MEMORY)
* @return old state, that is NULL for success, when the state was cleared and a pointer to a pending
* error when the error state was already set
*/
const char*
lumiera_error_set (const char * nerr)
{
@ -65,12 +59,6 @@ lumiera_error_set (const char * nerr)
}
/**
* Get and clear current error state.
* This function clears the error state, if it needs to be reused, one has to store it in a temporary
* variable.
* @return pointer to any pending error of this thread, NULL if no error is pending
*/
const char*
lumiera_error ()
{

13
src/lib/error.h
View file

@ -70,9 +70,22 @@ const char* LUMIERA_ERROR_##err = "LUMIERA_ERROR_" #err ":" msg
(({ERROR (flag, "%s", strchr(LUMIERA_ERROR_##err, ':')+1);}), \
lumiera_error_set(LUMIERA_ERROR_##err))
/**
* Set error state for the current thread.
* If the error state of the current thread was cleared, then set it, else preserve the old state.
* @param nerr name of the error with 'LUMIERA_ERROR_' prefix (example: LUMIERA_ERROR_NO_MEMORY)
* @return old state, that is NULL for success, when the state was cleared and a pointer to a pending
* error when the error state was already set
*/
const char*
lumiera_error_set (const char * err);
/**
* Get and clear current error state.
* This function clears the error state, if it needs to be reused, one has to store it in a temporary
* variable.
* @return pointer to any pending error of this thread, NULL if no error is pending
*/
const char*
lumiera_error ();

11
src/lib/mutex.c
View file

@ -31,11 +31,6 @@ LUMIERA_ERROR_DEFINE (MUTEX_UNLOCK, "Mutex unlocking failed");
LUMIERA_ERROR_DEFINE (MUTEX_DESTROY, "Mutex destroy failed");
/**
* Initialize a mutex variable
* @param self is a pointer to the mutex to be initialized
* @return self as given
*/
LumieraMutex
lumiera_mutex_init (LumieraMutex self)
{
@ -46,11 +41,7 @@ lumiera_mutex_init (LumieraMutex self)
return self;
}
/**
* Destroy a mutex variable
* @param self is a pointer to the mutex to be destroyed
* @return self as given
*/
LumieraMutex
lumiera_mutex_destroy (LumieraMutex self)
{

10
src/lib/mutex.h
View file

@ -51,10 +51,20 @@ typedef struct lumiera_mutex_struct lumiera_mutex;
typedef lumiera_mutex* LumieraMutex;
/**
* Initialize a mutex variable
* @param self is a pointer to the mutex to be initialized
* @return self as given
*/
LumieraMutex
lumiera_mutex_init (LumieraMutex self);
/**
* Destroy a mutex variable
* @param self is a pointer to the mutex to be destroyed
* @return self as given
*/
LumieraMutex
lumiera_mutex_destroy (LumieraMutex self);

20
src/lib/plugin.c
View file

@ -111,10 +111,6 @@ lumiera_plugin_name_cmp (const void* a, const void* b)
return strcmp (((struct lumiera_plugin*) a)->name, ((struct lumiera_plugin*) b)->name);
}
/**
* Initialize the plugin system.
* always succeeds or aborts
*/
void
lumiera_init_plugin (void)
{
@ -173,17 +169,6 @@ lumiera_plugin_lookup (struct lumiera_plugin* self, const char* path)
}
/**
* Make an interface available.
* To use an interface provided by a plugin it must be opened first. It is allowed to open an interface
* more than once. Each open must be paired with a close.
* @param name name of the plugin to use.
* @param interface name of the interface to open.
* @param min_revision the size of the interface structure is used as measure of a minimal required
* revision (new functions are appended at the end)
* @return handle to the interface or NULL in case of a error. The application shall cast this handle to
* the actual interface type.
*/
struct lumiera_interface*
lumiera_interface_open (const char* name, const char* interface, size_t min_revision)
{
@ -311,11 +296,6 @@ lumiera_interface_open (const char* name, const char* interface, size_t min_revi
return NULL;
}
/**
* Close an interface. Does not free associated resources
* Calling this function with self==NULL is legal. Every interface handle must be closed only once.
* @param ptr interface to be closed
*/
void
lumiera_interface_close (void* ptr)
{

20
src/lib/plugin.h
View file

@ -96,14 +96,34 @@ struct lumiera_interface
int (*close)(void);
};
/**
* Initialize the plugin system.
* always succeeds or aborts
*/
void
lumiera_init_plugin (void);
/**
* Make an interface available.
* To use an interface provided by a plugin it must be opened first. It is allowed to open an interface
* more than once. Each open must be paired with a close.
* @param name name of the plugin to use.
* @param interface name of the interface to open.
* @param min_revision the size of the interface structure is used as measure of a minimal required
* revision (new functions are appended at the end)
* @return handle to the interface or NULL in case of a error. The application shall cast this handle to
* the actual interface type.
*/
struct lumiera_interface*
lumiera_interface_open (const char* plugin, const char* name, size_t min_revision);
/**
* Close an interface. Does not free associated resources
* Calling this function with self==NULL is legal. Every interface handle must be closed only once.
* @param ptr interface to be closed
*/
void
lumiera_interface_close (void* self);

44
src/lib/references.c
View file

@ -33,15 +33,6 @@
*/
/**
* Construct an initial strong reference from an object.
* For every object which should be managed with references you need to construct an initial strong reference
* which then will be used to initialize all further references.
* @param self pointer to the reference to be initialized
* @param obj pointer to the object being referenced
* @param dtor destructor function which will be called on obj when the last strong reference gets deleted
* @return self as given
*/
LumieraReference
lumiera_reference_strong_init_once (LumieraReference self, void* obj, void (*dtor)(void*))
{
@ -58,15 +49,7 @@ lumiera_reference_strong_init_once (LumieraReference self, void* obj, void (*dto
return self;
}
/**
* Destroy a reference.
* All references need to be destroyed when not used any more.
* When the last strong reference gets destroyed, the object's destructor is called.
* Remaining weak references stay invalidated then until they get destroyed too.
* @param self reference to be destroyed
* @return self as given
* destroying a reference is not thread safe as far as 2 threads try to concurrently destroy it!
*/
LumieraReference
lumiera_reference_destroy (LumieraReference self)
{
@ -113,12 +96,7 @@ lumiera_reference_destroy (LumieraReference self)
return self;
}
/**
* Copy construct a reference as strong reference
* @param source reference to copy
* @return self as strong reference (always for strong references) or NULL if source is an invalidated weak reference,
* in the later case the reference is constructed as weak reference barely to allow it be destroyed
*/
LumieraReference
lumiera_reference_strong_init (LumieraReference self, LumieraReference source)
{
@ -141,11 +119,7 @@ lumiera_reference_strong_init (LumieraReference self, LumieraReference source)
return self;
}
/**
* Copy construct a reference as weak reference
* @param source reference to copy
* @return self (always for strong references) or NULL if self is an invalidated weak reference
*/
LumieraReference
lumiera_reference_weak_init (LumieraReference self, LumieraReference source)
{
@ -164,12 +138,7 @@ lumiera_reference_weak_init (LumieraReference self, LumieraReference source)
return self;
}
/**
* turn a (strong) reference into a weak reference
* Weaken a reference may remove its last strong reference and thus destroy the object
* do nothing if the referene is already weak
* @return self or NULL if the final strong reference got removed,
*/
LumieraReference
lumiera_reference_weaken (restrict LumieraReference self)
{
@ -194,11 +163,6 @@ lumiera_reference_weaken (restrict LumieraReference self)
}
/**
* turn a (weak) reference into a strong reference
* only references of object which are not already destroyed can be strengthened
* @return self when successful, NULL when the object was already destroyed, 'self' stays a dead weak reference in that case
*/
LumieraReference
lumiera_reference_strengthen (LumieraReference self)
{

40
src/lib/references.h
View file

@ -69,10 +69,28 @@ lumiera_reference_ensuredestroyed (LumieraReference self)
}
/**
* Construct an initial strong reference from an object.
* For every object which should be managed with references you need to construct an initial strong reference
* which then will be used to initialize all further references.
* @param self pointer to the reference to be initialized
* @param obj pointer to the object being referenced
* @param dtor destructor function which will be called on obj when the last strong reference gets deleted
* @return self as given
*/
LumieraReference
lumiera_reference_strong_init_once (LumieraReference self, void* obj, void (*dtor)(void*));
/**
* Destroy a reference.
* All references need to be destroyed when not used any more.
* When the last strong reference gets destroyed, the object's destructor is called.
* Remaining weak references stay invalidated then until they get destroyed too.
* @param self reference to be destroyed
* @return self as given
* destroying a reference is not thread safe as far as 2 threads try to concurrently destroy it!
*/
LumieraReference
lumiera_reference_destroy (LumieraReference self);
@ -88,18 +106,40 @@ lumiera_reference_get (LumieraReference self)
}
/**
* Copy construct a reference as strong reference
* @param source reference to copy
* @return self as strong reference (always for strong references) or NULL if source is an invalidated weak reference,
* in the later case the reference is constructed as weak reference barely to allow it be destroyed
*/
LumieraReference
lumiera_reference_strong_init (LumieraReference self, LumieraReference source);
/**
* Copy construct a reference as weak reference
* @param source reference to copy
* @return self (always for strong references) or NULL if self is an invalidated weak reference
*/
LumieraReference
lumiera_reference_weak_init (LumieraReference self, LumieraReference source);
/**
* turn a (strong) reference into a weak reference
* Weaken a reference may remove its last strong reference and thus destroy the object
* do nothing if the referene is already weak
* @return self or NULL if the final strong reference got removed,
*/
LumieraReference
lumiera_reference_weaken (restrict LumieraReference self);
/**
* turn a (weak) reference into a strong reference
* only references of object which are not already destroyed can be strengthened
* @return self when successful, NULL when the object was already destroyed, 'self' stays a dead weak reference in that case
*/
LumieraReference
lumiera_reference_strengthen (LumieraReference self);

33
src/lib/rwlock.c
View file

@ -34,11 +34,6 @@ LUMIERA_ERROR_DEFINE(RWLOCK_WLOCK, "wlock");
*/
/**
* Initialize a rwlock
* @param self is a pointer to the rwlock to be initialized
* @return self as given
*/
LumieraRWLock
lumiera_rwlock_init (LumieraRWLock self)
{
@ -49,11 +44,7 @@ lumiera_rwlock_init (LumieraRWLock self)
return self;
}
/**
* destroy a rwlock
* @param self is a pointer to the rwlock to be initialized
* @return self on success or NULL at error
*/
LumieraRWLock
lumiera_rwlock_destroy (LumieraRWLock self)
{
@ -68,13 +59,7 @@ lumiera_rwlock_destroy (LumieraRWLock self)
/**
* initialize a rwlockacquirer state
* @param self rwlockacquirer to be initialized, must be an automatic variable
* @param rwlock associated rwlock
* @param state initial state of the mutex, either LUMIERA_RDLOCKED, LUMIERA_WRLOCKED or LUMIERA_UNLOCKED
* @return self as given or NULL on error
*/
LumieraRWLockacquirer
lumiera_rwlockacquirer_init (LumieraRWLockacquirer self, LumieraRWLock rwlock, enum lumiera_lockstate state)
{
@ -118,12 +103,7 @@ lumiera_rwlockacquirer_init (LumieraRWLockacquirer self, LumieraRWLock rwlock, e
}
/**
* readlock the rwlock.
* must not already be locked
* @param self rwlockacquirer associated with a rwlock
* @return self as given or NULL on error
*/
LumieraRWLockacquirer
lumiera_rwlockacquirer_rdlock (LumieraRWLockacquirer self)
{
@ -149,12 +129,7 @@ lumiera_rwlockacquirer_rdlock (LumieraRWLockacquirer self)
}
/**
* writelock the rwlock.
* must not already be locked
* @param self rwlockacquirer associated with a rwlock
* @return self as given or NULL on error
*/
LumieraRWLockacquirer
lumiera_rwlockacquirer_wrlock (LumieraRWLockacquirer self)
{

33
src/lib/rwlock.h
View file

@ -55,11 +55,19 @@ struct lumiera_rwlock_struct
typedef struct lumiera_rwlock_struct lumiera_rwlock;
typedef lumiera_rwlock* LumieraRWLock;
/**
* Initialize a rwlock
* @param self is a pointer to the rwlock to be initialized
* @return self as given
*/
LumieraRWLock
lumiera_rwlock_init (LumieraRWLock self);
/**
* destroy a rwlock
* @param self is a pointer to the rwlock to be initialized
* @return self on success or NULL at error
*/
LumieraRWLock
lumiera_rwlock_destroy (LumieraRWLock self);
@ -88,14 +96,31 @@ lumiera_rwlockacquirer_ensureunlocked (LumieraRWLockacquirer self)
#define lumiera_rwlockacquirer \
lumiera_rwlockacquirer NOBUG_CLEANUP(lumiera_rwlockacquirer_ensureunlocked)
/**
* initialize a rwlockacquirer state
* @param self rwlockacquirer to be initialized, must be an automatic variable
* @param rwlock associated rwlock
* @param state initial state of the mutex, either LUMIERA_RDLOCKED, LUMIERA_WRLOCKED or LUMIERA_UNLOCKED
* @return self as given or NULL on error
*/
LumieraRWLockacquirer
lumiera_rwlockacquirer_init (LumieraRWLockacquirer self, LumieraRWLock rwlock, enum lumiera_lockstate state);
/**
* readlock the rwlock.
* must not already be locked
* @param self rwlockacquirer associated with a rwlock
* @return self as given or NULL on error
*/
LumieraRWLockacquirer
lumiera_rwlockacquirer_rdlock (LumieraRWLockacquirer self);
/**
* writelock the rwlock.
* must not already be locked
* @param self rwlockacquirer associated with a rwlock
* @return self as given or NULL on error
*/
LumieraRWLockacquirer
lumiera_rwlockacquirer_wrlock (LumieraRWLockacquirer self);

52
src/lib/safeclib.c
View file

@ -26,19 +26,9 @@
#include <stdint.h>
#include <stdarg.h>
/**
* @file
* Portable and safe wrapers around some clib functions and some tools
*/
LUMIERA_ERROR_DEFINE (NO_MEMORY, "Out of Memory!");
/**
* Allocate memory.
* always succeeds or dies
* @param size memory to be allocated
* @return pointer to the allocated memory
*/
void*
lumiera_malloc (size_t size)
{
@ -49,13 +39,6 @@ lumiera_malloc (size_t size)
}
/**
* Allocate cleared memory for an array.
* always succeeds or dies
* @param n number of elements
* @param size memory to be allocated
* @return pointer to the allocated memory
*/
void*
lumiera_calloc (size_t n, size_t size)
{
@ -66,13 +49,6 @@ lumiera_calloc (size_t n, size_t size)
}
/**
* Duplicate a C string.
* always succeeds or dies
* @param str string to be copied
* @param len maximal length to be copied
* @return pointer to the new string, "" if NULL was passed as str
*/
char*
lumiera_strndup (const char* str, size_t len)
{
@ -88,14 +64,6 @@ lumiera_strndup (const char* str, size_t len)
}
/**
* Compare two C strings.
* Handles NULL pointers as "", shortcut for same addresses
* @param a first string for comparsion
* @param b second string for comparsion
* @param len maximal length for the comparsion
* @return 0 if the strings are identical, -1 if smaller 1 if bigger.
*/
int
lumiera_strncmp (const char* a, const char* b, size_t len)
{
@ -103,12 +71,6 @@ lumiera_strncmp (const char* a, const char* b, size_t len)
}
/**
* check 2 strings for identity.
* @param a first string for comparsion
* @param b second string for comparsion
* @return 1 when the strings are the the same, 0 if not.
*/
int
lumiera_streq (const char* a, const char* b)
{
@ -116,11 +78,6 @@ lumiera_streq (const char* a, const char* b)
}
/**
* Round robin temporary buffers.
* This provides 64 buffers per thread which are recycled with each use.
* The idea here is to have fast buffers for temporal data without need for explicit heap management.
*/
struct lumiera_tmpbuf_struct
{
void* buffers[64];
@ -147,10 +104,6 @@ lumiera_tmpbuf_init (void)
}
/**
* free all buffers associated with this thread.
* This function is called automatically, usually one doesnt need to call it.
*/
void
lumiera_tmpbuf_freeall (void)
{
@ -166,11 +119,6 @@ lumiera_tmpbuf_freeall (void)
}
/**
* Query a thread local buffer.
* @param size minimal needed size for the buffer
* @return the buffer
*/
void*
lumiera_tmpbuf_provide (size_t size)
{