X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/baa212aa2fc1e0f91b0e9a9536db52f1657331a8..9eb8b5a3c4a65bf441c487ecef308654d4f384f4:/src/xbt/dynar.c

diff --git a/src/xbt/dynar.c b/src/xbt/dynar.c
index 9a85b80119..a9e768eeb3 100644
--- a/src/xbt/dynar.c
+++ b/src/xbt/dynar.c
@@ -7,6 +7,7 @@
 /* This program is free software; you can redistribute it and/or modify it
  * under the terms of the license (GNU LGPL) which comes with this package. */
 
+#include "portable.h" /* SIZEOF_MAX */
 #include "xbt/misc.h"
 #include "xbt/sysdep.h"
 #include "xbt/log.h"
@@ -14,15 +15,11 @@
 #include "xbt/dynar.h"
 #include <sys/types.h>
 
+#include "xbt/dynar_private.h" /* type definition, which we share with the 
+	 		 	  code in charge of sending this across the net */
+
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dynar,xbt,"Dynamic arrays");
 
-typedef struct xbt_dynar_s {
-  unsigned long          size;
-  unsigned long          used;
-  unsigned long          elmsize;
-  void           *data;
-  void_f_pvoid_t *free_f;
-} s_xbt_dynar_t;
 
 #define __sanity_check_dynar(dynar)       \
            xbt_assert0(dynar,           \
@@ -74,7 +71,7 @@ _xbt_dynar_expand(xbt_dynar_t const dynar,
     if (old_data) {
       memcpy(new_data, old_data, used_length);
       _xbt_clear_mem(old_data, old_length);
-      xbt_free(old_data);
+      free(old_data);
     }
 
     _xbt_clear_mem(new_data + used_length, new_length - used_length);
@@ -118,10 +115,10 @@ _xbt_dynar_put_elm(const xbt_dynar_t  dynar,
   memcpy(elm, src, elmsize);
 }
 
-/**
- * xbt_dynar_new:
- * @elm_size: size of each element in the dynar
- * @free_func: function to call each time we want to get rid of an element (or NULL if nothing to do).
+/** @brief Constructor
+ * 
+ * \param elmsize size of each element in the dynar
+ * \param free_f function to call each time we want to get rid of an element (or NULL if nothing to do).
  *
  * Creates a new dynar. If a free_func is provided, the elements have to be
  * pointer of pointer. That is to say that dynars can contain either base
@@ -142,12 +139,12 @@ xbt_dynar_new(const unsigned long           elmsize,
   return dynar;
 }
 
-/**
- * xbt_dynar_free_container:
- * @dynar: poor victim
+/** @brief Destructor of the structure not touching to the content
+ * 
+ * \param dynar poor victim
  *
- * kilkil a dynar BUT NOT its content. Ie, the array is freed, but not what
- * its contain points to.
+ * kilkil a dynar BUT NOT its content. Ie, the array is freed, but the content
+ * is not touched (the \a free_f function is not used)
  */
 void
 xbt_dynar_free_container(xbt_dynar_t *dynar) {
@@ -155,21 +152,19 @@ xbt_dynar_free_container(xbt_dynar_t *dynar) {
 
     if ((*dynar)->data) {
       _xbt_clear_mem((*dynar)->data, (*dynar)->size);
-      xbt_free((*dynar)->data);
+      free((*dynar)->data);
     }
 
     _xbt_clear_mem(*dynar, sizeof(s_xbt_dynar_t));
 
-    xbt_free(*dynar);
+    free(*dynar);
     *dynar=NULL;
   }
 }
 
-/**
- * xbt_dynar_reset:
- * @dynar: who to squeeze
+/** @brief Frees the content and set the size to 0
  *
- * Frees the content and set the size to 0
+ * \param dynar who to squeeze
  */
 void
 xbt_dynar_reset(xbt_dynar_t const dynar) {
@@ -182,16 +177,16 @@ xbt_dynar_reset(xbt_dynar_t const dynar) {
   }
 
   if (dynar->data)
-    xbt_free(dynar->data);
+    free(dynar->data);
 
   dynar->size = 0;
   dynar->used = 0;
   dynar->data = NULL;
 }
 
-/**
- * xbt_dynar_free:
- * @dynar: poor victim
+/** @brief Destructor
+ * 
+ * \param dynar poor victim
  *
  * kilkil a dynar and its content
  */
@@ -204,24 +199,20 @@ xbt_dynar_free(xbt_dynar_t * dynar) {
   }
 }
 
-/**
- * xbt_dynar_length:
- * @dynar: the dynar we want to mesure
- *
- * Returns the count of elements in a dynar
+/** @brief Count of dynar's elements
+ * 
+ * \param dynar the dynar we want to mesure
  */
 unsigned long
 xbt_dynar_length(const xbt_dynar_t dynar) {
   return (dynar ? (unsigned long) dynar->used : (unsigned long)0);
 }
 
-/**
- * xbt_dynar_get_cpy:
- * @dynar: information dealer
- * @idx: index of the slot we want to retrive
- * @dst: where to pu the result to.
+/** @brief Retrieve a copy of the Nth element of a dynar.
  *
- * Retrieve a copy of the Nth element of a dynar.
+ * \param dynar information dealer
+ * \param idx index of the slot we want to retrive
+ * \param[out] dst where to put the result to.
  */
 void
 xbt_dynar_get_cpy(const xbt_dynar_t dynar,
@@ -235,14 +226,14 @@ xbt_dynar_get_cpy(const xbt_dynar_t dynar,
   _xbt_dynar_get_elm(dst, dynar, idx);
 }
 
-/**
- * xbt_dynar_get_ptr:
- * @dynar: information dealer
- * @idx: index of the slot we want to retrive
- * @dst: where to pu the result to.
+/** @brief Retrieve a pointer to the Nth element of a dynar.
+ *
+ * \param dynar information dealer
+ * \param idx index of the slot we want to retrieve
+ * \return the \a idx-th element of \a dynar.
  *
- * Retrieve the Nth element of a dynar. Warning, the returned value is the actual content of 
- * the dynar. Make a copy before fooling with it.
+ * \warning The returned value is the actual content of the dynar. 
+ * Make a copy before fooling with it.
  */
 void*
 xbt_dynar_get_ptr(const xbt_dynar_t dynar,
@@ -255,15 +246,13 @@ xbt_dynar_get_ptr(const xbt_dynar_t dynar,
   return _xbt_dynar_elm(dynar, idx);
 }
 
-/**
- * xbt_dynar_set:
- * @dynar:
- * @idx:
- * @src: What will be feeded to the dynar
+/** @brief Set the Nth element of a dynar (expended if needed). Previous value at this position is NOT freed
+ * 
+ * \param dynar information dealer
+ * \param idx index of the slot we want to modify
+ * \param src What will be feeded to the dynar
  *
- * Set the Nth element of a dynar, expanding the dynar if needed, BUT NOT freeing
- * the previous value at this position. If you want to free the previous content,
- * use xbt_dynar_replace().
+ * If you want to free the previous content, use xbt_dynar_replace().
  */
 void
 xbt_dynar_set(xbt_dynar_t         dynar,
@@ -282,11 +271,11 @@ xbt_dynar_set(xbt_dynar_t         dynar,
   _xbt_dynar_put_elm(dynar, idx, src);
 }
 
-/**
- * xbt_dynar_replace:
- * @dynar:
- * @idx:
- * @object:
+/** @brief Set the Nth element of a dynar (expended if needed). Previous value is freed
+ *
+ * \param dynar
+ * \param idx
+ * \param object
  *
  * Set the Nth element of a dynar, expanding the dynar if needed, AND DO
  * free the previous value at this position. If you don't want to free the
@@ -309,16 +298,14 @@ xbt_dynar_replace(xbt_dynar_t         dynar,
   xbt_dynar_set(dynar, idx, object);
 }
 
-/**
- * xbt_dynar_insert_at_ptr:
+/** @brief Make room for a new element, and return a pointer to it
  * 
- * Make room for a new element in the dynar, and return a pointer to
- * its position. You can then use regular affectation to set its value
- * instead of relying on the slow memcpy
+ * You can then use regular affectation to set its value instead of relying 
+ * on the slow memcpy. This is what xbt_dynar_insert_at_as() does.
  */
 void *
 xbt_dynar_insert_at_ptr(xbt_dynar_t const dynar,
-			 const int            idx) {
+			const int            idx) {
    
   __sanity_check_dynar(dynar);
   __sanity_check_idx(idx);
@@ -344,20 +331,16 @@ xbt_dynar_insert_at_ptr(xbt_dynar_t const dynar,
   }
 }
 
-/**
- * xbt_dynar_insert_at:
- * @dynar:
- * @idx:
- * @src: What will be feeded to the dynar
- *
+/** @brief Set the Nth dynar's element, expending the dynar and sliding the previous values to the right
+ * 
  * Set the Nth element of a dynar, expanding the dynar if needed, and
  * moving the previously existing value and all subsequent ones to one
  * position right in the dynar.
  */
 void
 xbt_dynar_insert_at(xbt_dynar_t  const dynar,
-                     const int            idx,
-                     const void   * const src) {
+		    const int            idx,
+		    const void   * const src) {
 
   /* checks done in xbt_dynar_insert_at_ptr */
   memcpy(xbt_dynar_insert_at_ptr(dynar,idx),
@@ -365,11 +348,7 @@ xbt_dynar_insert_at(xbt_dynar_t  const dynar,
 	 dynar->elmsize);
 }
 
-/**
- * xbt_dynar_remove_at:
- * @dynar: 
- * @idx:
- * @object:
+/** @brief Remove the Nth dynar's element, sliding the previous values to the left
  *
  * Get the Nth element of a dynar, removing it from the dynar and moving
  * all subsequent values to one position left in the dynar.
@@ -404,23 +383,17 @@ xbt_dynar_remove_at(xbt_dynar_t  const dynar,
   }
 }
 
-/**
- * xbt_dynar_push_ptr:
- * 
- * Make room at the end of the dynar for a new element, and return a pointer to it
+/** @brief Make room at the end of the dynar for a new element, and return a pointer to it.
+ *
+ * You can then use regular affectation to set its value instead of relying 
+ * on the slow memcpy. This is what xbt_dynar_push_as() does.
  */
 void *
 xbt_dynar_push_ptr(xbt_dynar_t  const dynar) {
   return xbt_dynar_insert_at_ptr(dynar, dynar->used);    
 }
 
-/**
- * xbt_dynar_push:
- * @dynar:
- * @src:
- *
- * Add an element at the end of the dynar
- */
+/** @brief Add an element at the end of the dynar */
 void
 xbt_dynar_push(xbt_dynar_t  const dynar,
                 const void   * const src) {
@@ -428,12 +401,10 @@ xbt_dynar_push(xbt_dynar_t  const dynar,
   xbt_dynar_insert_at(dynar, dynar->used, src); 
 }
 
-/**
- * xbt_dynar_pop_ptr:
- * @dynar:
- * @dst:
+/** @brief Mark the last dynar's element as unused and return a pointer to it.
  *
- * Make the last element of the dynar as unused and return a pointer to it.
+ * You can then use regular affectation to set its value instead of relying 
+ * on the slow memcpy. This is what xbt_dynar_pop_as() does.
  */
 void *
 xbt_dynar_pop_ptr(xbt_dynar_t  const dynar) {
@@ -444,13 +415,7 @@ xbt_dynar_pop_ptr(xbt_dynar_t  const dynar) {
   return _xbt_dynar_elm(dynar,dynar->used);
 }
 
-/**
- * xbt_dynar_pop:
- * @dynar:
- * @dst:
- *
- * Get and remove the last element of the dynar
- */
+/** @brief Get and remove the last element of the dynar */
 void
 xbt_dynar_pop(xbt_dynar_t  const dynar,
                void         * const dst) {
@@ -460,13 +425,9 @@ xbt_dynar_pop(xbt_dynar_t  const dynar,
   xbt_dynar_remove_at(dynar, dynar->used-1, dst);
 }
 
-/**
- * xbt_dynar_unshift:
- * @dynar:
- * @src:
+/** @brief Add an element at the begining of the dynar.
  *
- * Add an element at the begining of the dynar (rather long, Use
- * xbt_dynar_push() when possible)
+ * This is less efficient than xbt_dynar_push()
  */
 void
 xbt_dynar_unshift(xbt_dynar_t  const dynar,
@@ -476,13 +437,9 @@ xbt_dynar_unshift(xbt_dynar_t  const dynar,
   xbt_dynar_insert_at(dynar, 0, src);
 }
 
-/**
- * xbt_dynar_shift:
- * @dynar:
- * @dst:
+/** @brief Get and remove the first element of the dynar.
  *
- * Get and remove the first element of the dynar (rather long, Use
- * xbt_dynar_pop() when possible)
+ * This is less efficient than xbt_dynar_pop()
  */
 void
 xbt_dynar_shift(xbt_dynar_t  const dynar,
@@ -492,13 +449,10 @@ xbt_dynar_shift(xbt_dynar_t  const dynar,
   xbt_dynar_remove_at(dynar, 0, dst);
 }
 
-/**
- * xbt_dynar_map:
- * @dynar:
- * @operator:
+/** @brief Apply a function to each member of a dynar
  *
- * Apply a function to each member of a dynar (this function may change the
- * value of the element itself, but should not mess with the dynar).
+ * The mapped function may change the value of the element itself, 
+ * but should not mess with the structure of the dynar.
  */
 void
 xbt_dynar_map(const xbt_dynar_t  dynar,
@@ -507,7 +461,7 @@ xbt_dynar_map(const xbt_dynar_t  dynar,
   __sanity_check_dynar(dynar);
 
   {
-    char         elm[64];
+    char         elm[SIZEOF_MAX];
     const unsigned long used = dynar->used;
     unsigned long       i    = 0;
 
@@ -518,30 +472,20 @@ xbt_dynar_map(const xbt_dynar_t  dynar,
   }
 }
 
-/**
- * xbt_dynar_cursor_first:
- *
- * Put the cursor at the begining of the dynar. (actually, one step before
- * the begining, so that you can iterate over the dynar with a for loop).
- *
- * Dynar cursor are as dumb as possible. If you insert or remove elements
- * from the dynar between the creation and end, you'll fuck up your
- * cursors.
+/** @brief Put the cursor at the begining of the dynar.
  *
+ * Actually, the cursor is set one step before the begining, so that you
+ * can iterate over the dynar with a for loop.
  */
 void
 xbt_dynar_cursor_first(const xbt_dynar_t dynar,
-			int        * const cursor) {
+		       int        * const cursor) {
 
   DEBUG1("Set cursor on %p to the first position",(void*)dynar);
   *cursor = 0;
 }
 
-/**
- * xbt_dynar_cursor_step:
- *
- * Move the cursor to the next value (and return true), or return false.
- */
+/** @brief Move the cursor to the next value */
 void
 xbt_dynar_cursor_step(const xbt_dynar_t dynar,
 		       int        * const cursor) {
@@ -549,11 +493,7 @@ xbt_dynar_cursor_step(const xbt_dynar_t dynar,
   (*cursor)++;
 }
 
-/**
- * xbt_dynar_cursor_get:
- *
- * Get the current value of the cursor
- */
+/** @brief Get the data currently pointed by the cursor */
 int
 xbt_dynar_cursor_get(const xbt_dynar_t dynar,
 		      int                * const cursor,
@@ -576,12 +516,9 @@ xbt_dynar_cursor_get(const xbt_dynar_t dynar,
 
 }
 
-/**
- * xbt_dynar_cursor_rm:
- * @dynar:
- * @cursor:
+/** @brief Removes and free the entry pointed by the cursor 
  *
- * Remove (free) the entry pointed by the cursor, for use in the middle of a foreach
+ * This function can be used while traversing without problem.
  */
 void xbt_dynar_cursor_rm(xbt_dynar_t dynar,
 			  int          * const cursor) {
@@ -593,7 +530,7 @@ void xbt_dynar_cursor_rm(xbt_dynar_t dynar,
       dst=xbt_malloc(dynar->elmsize);
       xbt_dynar_remove_at(dynar,(*cursor)--,dst);
       (dynar->free_f)(dst);
-      xbt_free(dst);
+      free(dst);
     } else {
       DEBUG0("Ok, we dont care about the element without free function");
       xbt_dynar_remove_at(dynar,(*cursor)--,NULL);