[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