Commit dd04ef5f authored by Philipp Schafft's avatar Philipp Schafft 🦁

Update: Added comments to refobject.h

parent 2f938b85
...@@ -6,6 +6,10 @@ ...@@ -6,6 +6,10 @@
* Copyright 2018, Philipp "ph3-der-loewe" Schafft <lion@lion.leolix.org>, * Copyright 2018, Philipp "ph3-der-loewe" Schafft <lion@lion.leolix.org>,
*/ */
/* This file contains the API for the refobject helper type.
* The refobject helper type is a base type that allows building other types with safe reference counting.
*/
#ifndef __REFOBJECT_H__ #ifndef __REFOBJECT_H__
#define __REFOBJECT_H__ #define __REFOBJECT_H__
...@@ -18,6 +22,20 @@ ...@@ -18,6 +22,20 @@
#include "icecasttypes.h" #include "icecasttypes.h"
#include "compat.h" #include "compat.h"
/* The following macros are defined. The definition depends on if the compiler
* supports transparent unions. If supported full type checking is enabled.
* If the compiler does not support transparent unions, we fall back to using
* (void*) pointers.
*
* REFOBJECT_NULL
* Can be used to set an refobject to NULL.
* REFOBJECT_IS_NULL(x)
* Can be used to check if the refobject x is NULL.
* Checking by doing (x == NULL) does not work with transparent unions
* as the operation is only defined for it's members.
* REFOBJECT_TO_TYPE(type,x)
* This casts the refobject (x) to the type (type).
*/
#ifdef HAVE_TYPE_ATTRIBUTE_TRANSPARENT_UNION #ifdef HAVE_TYPE_ATTRIBUTE_TRANSPARENT_UNION
#define REFOBJECT_NULL ((refobject_t)(refobject_base_t*)NULL) #define REFOBJECT_NULL ((refobject_t)(refobject_base_t*)NULL)
#define REFOBJECT_IS_NULL(x) (((refobject_t)(x)).refobject_base == NULL) #define REFOBJECT_IS_NULL(x) (((refobject_t)(x)).refobject_base == NULL)
...@@ -28,8 +46,19 @@ ...@@ -28,8 +46,19 @@
#define REFOBJECT_TO_TYPE(x,y) ((y)(x)) #define REFOBJECT_TO_TYPE(x,y) ((y)(x))
#endif #endif
/* Type used for callback called then the object is actually freed
* That is once all references to it are gone.
*
* If the callback does not set *userdata to NULL *userdata will
* be freed automatically by calling free(3).
*
* This function must not try to deallocate or alter self.
*/
typedef void (*refobject_free_t)(refobject_t self, void **userdata); typedef void (*refobject_free_t)(refobject_t self, void **userdata);
/* Only defined here as the size must be publically known.
* DO NOT use any of the members in here directly!
*/
struct refobject_base_tag { struct refobject_base_tag {
size_t refc; size_t refc;
mutex_t lock; mutex_t lock;
...@@ -39,12 +68,33 @@ struct refobject_base_tag { ...@@ -39,12 +68,33 @@ struct refobject_base_tag {
refobject_t associated; refobject_t associated;
}; };
/* Create a new refobject
* The total length of the new object is given by len (see malloc(3)),
* the callback called on free is given by freecb (see refobject_free_t above),
* the userdata us given by userdata,
* the name for the object is given by name, and
* the associated refobject is given by associated.
*
* All parameters beside len are optional and can be NULL/REFOBJECT_NULL.
* If no freecb is given the userdata is freed (see refobject_free_t above).
*/
refobject_t refobject_new(size_t len, refobject_free_t freecb, void *userdata, const char *name, refobject_t associated); refobject_t refobject_new(size_t len, refobject_free_t freecb, void *userdata, const char *name, refobject_t associated);
/* This increases the reference counter of the object */
int refobject_ref(refobject_t self); int refobject_ref(refobject_t self);
/* This decreases the reference counter of the object.
* If the object's reference counter reaches zero the object is freed.
*/
int refobject_unref(refobject_t self); int refobject_unref(refobject_t self);
/* This gets and sets the userdata */
void * refobject_get_userdata(refobject_t self); void * refobject_get_userdata(refobject_t self);
int refobject_set_userdata(refobject_t self, void *userdata); int refobject_set_userdata(refobject_t self, void *userdata);
/* This gets the object's name */
const char * refobject_get_name(refobject_t self); const char * refobject_get_name(refobject_t self);
/* This gets the object's associated object. */
refobject_t refobject_get_associated(refobject_t self); refobject_t refobject_get_associated(refobject_t self);
#endif #endif
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment