X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/2539fff313cbd67c45b8490f7961e45e358d9ba2..ae31c9605daeec056883c914f4f0d4cd676a8d4b:/src/xbt/dynar.c

diff --git a/src/xbt/dynar.c b/src/xbt/dynar.c
index 4fa31105c1..8534dde7c8 100644
--- a/src/xbt/dynar.c
+++ b/src/xbt/dynar.c
@@ -1,13 +1,13 @@
 /* $Id$ */
 
-/* a generic DYNamic ARray                                                  */
+/* a generic DYNamic ARray implementation.                                  */
 
-/* Authors: Martin Quinson                                                  */
-/* Copyright (C) 2003 the OURAGAN project.                                  */
+/* Copyright (c) 2003, 2004 Martin Quinson. All rights reserved.            */
 
 /* 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. */
+ * 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"
@@ -15,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,           \
@@ -75,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);
@@ -119,10 +115,16 @@ _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).
+void
+xbt_dynar_dump(xbt_dynar_t dynar) {
+  INFO5("Dynar dump: size=%lu; used=%lu; elmsize=%lu; data=%p; free_f=%p",
+	dynar->size, dynar->used, dynar->elmsize, dynar->data, dynar->free_f);
+}	
+
+/** @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
@@ -143,12 +145,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) {
@@ -156,21 +158,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) {
@@ -183,16 +183,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
  */
@@ -205,24 +205,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,
@@ -236,18 +232,18 @@ 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.
  *
- * 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.
+ * \param dynar information dealer
+ * \param idx index of the slot we want to retrieve
+ * \return the \a idx-th element of \a dynar.
+ *
+ * \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,
-		   const int          idx) {
+	   const int          idx) {
 
   __sanity_check_dynar(dynar);
   __sanity_check_idx(idx);
@@ -256,15 +252,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,
@@ -283,11 +277,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
@@ -310,16 +304,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);
@@ -345,20 +337,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),
@@ -366,11 +354,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.
@@ -380,48 +364,42 @@ xbt_dynar_remove_at(xbt_dynar_t  const dynar,
                      const int            idx,
                      void         * const object) {
 
+  unsigned long nb_shift;
+  unsigned long offset;
+
   __sanity_check_dynar(dynar);
   __sanity_check_idx(idx);
   __check_inbound_idx(dynar, idx);
 
-  if (object)
+  if (object) {
     _xbt_dynar_get_elm(object, dynar, idx);
+  } else if (dynar->free_f) {
+    char elm[SIZEOF_MAX];
+    _xbt_dynar_get_elm(elm, dynar, idx);
+    (*dynar->free_f)(elm);
+  }
 
-  {
-    const unsigned long old_used = dynar->used;
-    const unsigned long new_used = old_used - 1;
-
-    const unsigned long nb_shift =  old_used-1 - idx;
-    const unsigned long elmsize  =  dynar->elmsize;
-
-    const unsigned long offset   =  nb_shift*elmsize;
-
-    void * const elm_src  = _xbt_dynar_elm(dynar, idx+1);
-    void * const elm_dst  = _xbt_dynar_elm(dynar, idx);
+  nb_shift =  dynar->used-1 - idx;
+  offset   =  nb_shift * dynar->elmsize;
 
-    memmove(elm_dst, elm_src, offset);
+  memmove(_xbt_dynar_elm(dynar, idx),
+          _xbt_dynar_elm(dynar, idx+1), 
+          offset);
 
-    dynar->used = new_used;
-  }
+  dynar->used--;
 }
 
-/**
- * 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) {
@@ -429,12 +407,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) {
@@ -445,13 +421,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) {
@@ -461,13 +431,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,
@@ -477,13 +443,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,
@@ -493,13 +455,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,
@@ -508,7 +467,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;
 
@@ -519,30 +478,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) {
@@ -550,11 +499,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,
@@ -577,12 +522,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) {
@@ -594,7 +536,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);