[asterisk-commits] rizzo: branch rizzo/astobj2 r47222 - in
/team/rizzo/astobj2: include/asterisk...
asterisk-commits at lists.digium.com
asterisk-commits at lists.digium.com
Mon Nov 6 08:25:36 MST 2006
Author: rizzo
Date: Mon Nov 6 09:25:36 2006
New Revision: 47222
URL: http://svn.digium.com/view/asterisk?rev=47222&view=rev
Log:
a bit of documentation
Modified:
team/rizzo/astobj2/include/asterisk/astobj2.h
team/rizzo/astobj2/main/astobj2.c
Modified: team/rizzo/astobj2/include/asterisk/astobj2.h
URL: http://svn.digium.com/view/asterisk/team/rizzo/astobj2/include/asterisk/astobj2.h?rev=47222&r1=47221&r2=47222&view=diff
==============================================================================
--- team/rizzo/astobj2/include/asterisk/astobj2.h (original)
+++ team/rizzo/astobj2/include/asterisk/astobj2.h Mon Nov 6 09:25:36 2006
@@ -23,13 +23,59 @@
*
* \brief Object Model implementing objects and containers.
-These functions implement a container for user-defined object,
+These functions implement an abstraction for objects (with
+locks and reference counts) and containers for these user-defined objects,
supporting locking, reference counting and callbacks.
-The internal implementation of the container is, in principle,
-opaque to the user so we can use different data structures
-as needs arise. At the moment, however, the only internal
-data structure is a hash table. When other structures will
-be implemented, the initialization function may change.
+
+The internal implementation of the container is opaque to the user,
+so we can use different data structures as needs arise.
+
+At the moment, however, the only internal data structure is a hash
+table. When other structures will be implemented, the initialization
+function may change.
+
+USAGE - OBJECTS
+
+An object is a block of memory that must be allocated with the
+function astobj2_alloc(), and for which the system keeps track (with
+abit of help from the programmer) of the number of references around.
+When an object has no more references, it is destroyed, by first
+invoking whatever 'destructor' function the programmer specifies
+(it can be NULL), and then freeing the memory.
+This way objects can be shared without worrying who is in charge
+of freeing them.
+
+Basically, creating an object requires the size of the object and
+and a pointer to the destructor function:
+
+ struct foo *o;
+
+ o = astobj2_alloc(sizeof(struct foo), my_destructor_fn);
+
+The object returned has a refcount = 1.
+Note that the memory for the object is allocated and zeroed.
+- We cannot realloc() the object itself.
+- We cannot call free(o) to dispose of the object; rather we
+ tell the system that we do not need the reference anymore:
+
+ astobj2_ref(o, -1)
+
+ causing the destructor to be called (and then memory freed) when
+ the refcount goes to 0.
+
+- astobj2_ref(o, +1) can be used to modify the refcount on the
+ object in case we want to pass it around.
+
+- other calls on the object are astobj2_lock(obj), astobj2_unlock(),
+ astobj2_trylock(), to manipulate the lock.
+
+
+USAGE - CONTAINERS
+
+A containers is an abstract data structure where we can store
+objects, search them (hopefully in an efficient way), and iterate
+or apply a callback function to them. A container is just an object
+itself.
A container must first be allocated, specifying the initial
parameters. At the moment, this is done as follows:
@@ -51,34 +97,13 @@
- my_dump_fn() is a helper function used only for debugging.
A container knows little or nothing about the object itself,
-other than the fact that it has been created by astobj2_obj_alloc()
-(which is supposed to provide the extra data field used by
-the container code for manipulation).
+other than the fact that it has been created by astobj2_alloc()
All knowledge of the (user-defined) internals of the object
-is left to the (user-supplied) functions defined above.
-
-An object must be allocated with the function astobj2_obj_alloc(),
-which needs to know the size of the user-defined structure,
-and a pointer to a destructor function that is invoked
-when the object is not referenced anymore:
-
- struct foo *o;
-
- o = astobj2_obj_alloc(sizeof(struct foo), my_destructor_fn);
-
-the object return has a refcount = 1.
-Note that the memory for the object is zeroed.
-
-Note that we cannot do free(o) to dispose of the object
-created in this way. Rather, we need to call
-
- astobj2_ref(o, -1)
-
-which will drop a reference, causing the destructor to be
-called (and then memory freed) when the refcount goes to 0.
+is left to the (user-supplied) functions passed as arguments
+to astobj2_container_alloc().
If we want to insert the object in the container, we should
-initialize its fields -- especially, those used by my_hash_fn()
+initialize its fields -- especially, those used by my_hash_fn() --
to compute the bucket to use.
Once done, we can link an object to a container with
@@ -137,7 +162,7 @@
* - the returned pointer cannot be free()'d or realloc()'ed;
* rather, we just call astobj2_ref(o, -1);
*/
-void *astobj2_obj_alloc(const size_t data_size,
+void *astobj2_alloc(const size_t data_size,
astobj2_destructor_fn destructor_fn);
/*!
Modified: team/rizzo/astobj2/main/astobj2.c
URL: http://svn.digium.com/view/asterisk/team/rizzo/astobj2/main/astobj2.c?rev=47222&r1=47221&r2=47222&view=diff
==============================================================================
--- team/rizzo/astobj2/main/astobj2.c (original)
+++ team/rizzo/astobj2/main/astobj2.c Mon Nov 6 09:25:36 2006
@@ -124,7 +124,7 @@
* We always alloc at least the size of a void *,
* for debugging purposes.
*/
-void *astobj2_obj_alloc(size_t data_size, astobj2_destructor_fn destructor_fn)
+void *astobj2_alloc(size_t data_size, astobj2_destructor_fn destructor_fn)
{
/* allocation */
struct astobj2 *obj;
@@ -183,7 +183,7 @@
/* compute the container size */
size_t container_size = sizeof(struct container) + n_buckets * sizeof(struct bucket);
- struct container *c = astobj2_obj_alloc(container_size, container_destruct);
+ struct container *c = astobj2_alloc(container_size, container_destruct);
if (c == NULL)
return NULL;
@@ -506,7 +506,7 @@
struct astobj2_iterator ai;
if (prof_id == -1)
- prof_id = ast_add_profile("astobj2_obj_alloc", 0);
+ prof_id = ast_add_profile("astobj2_alloc", 0);
ast_cli(fd, "argc %d argv %s %s %s\n", argc, argv[0], argv[1], argv[2]);
lim = atoi(argv[2]);
@@ -521,12 +521,12 @@
/*
* fill the container with objects.
- * astobj2_obj_alloc() gives us a reference which we pass to the
+ * astobj2_alloc() gives us a reference which we pass to the
* container when we do the insert.
*/
for (i = 0; i < lim; i++) {
ast_mark(prof_id, 1 /* start */);
- obj = astobj2_obj_alloc(80, NULL);
+ obj = astobj2_alloc(80, NULL);
ast_mark(prof_id, 0 /* stop */);
ast_cli(fd, "object %d allocated as %p\n", i, obj);
sprintf(obj, "-- this is obj %d --", i);
More information about the asterisk-commits
mailing list