benn/lumiera_documentation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

documentation from condition.c and reference.c moved to .h

Browse source
This commit is contained in:
Mano Stienen 2008-07-11 08:15:08 +02:00
parent 1d8bc98429
commit 6838dbe12a
4 changed files with 55 additions and 50 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);

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);