X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/badb98df59530d5db81112b8c612a598cdac1c83..f4311d4e75331e015ee3cd2f2c45a833bb3c5ede:/src/gras/DataDesc/ddt_create.c

diff --git a/src/gras/DataDesc/ddt_create.c b/src/gras/DataDesc/ddt_create.c
index fe57496cf4..3323087298 100644
--- a/src/gras/DataDesc/ddt_create.c
+++ b/src/gras/DataDesc/ddt_create.c
@@ -44,9 +44,7 @@ static gras_datadesc_type_t gras_ddt_new(const char *name) {
 }
 
 /**
- * gras_datadesc_by_name:
- *
- * Retrieve a type from its name
+ * This returns NULL when no type of this name can be found
  */
 gras_datadesc_type_t gras_datadesc_by_name(const char *name) {
 
@@ -64,8 +62,6 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name) {
 }
 
 /**
- * gras_datadesc_by_id:
- *
  * Retrieve a type from its code
  */
 xbt_error_t gras_datadesc_by_id(long int              code,
@@ -76,8 +72,6 @@ xbt_error_t gras_datadesc_by_id(long int              code,
 }
 
 /**
- * gras_datadesc_scalar:
- *
  * Create a new scalar and give a pointer to it 
  */
 gras_datadesc_type_t 
@@ -103,44 +97,9 @@ gras_datadesc_type_t
   res = gras_ddt_new(name);
 
   for (arch = 0; arch < gras_arch_count; arch ++) {
-#if 0
-    long int sz;
-    long int mask;
-#endif
     res->size[arch]         = gras_arches[arch].sizeofs[type];
     res->alignment[arch]    = gras_arches[arch].boundaries[type];
     res->aligned_size[arch] = aligned(res->size[arch], res->alignment[arch]);
-/* FIXME: kill the following after discution with Oli */
-#if 0
-    sz = res->size[arch];
-    mask = sz;
-    
-    /* just in case you wonder, x>>1 == x/2 on all architectures when x>=0
-       and a size is always>=0 */
-    
-    /* make sure mask have all the bits under the biggest one of size set to 1
-       Example: size=000100101 => mask=0000111111 */
-    while ((sz >>= 1)) {
-      mask |= sz;
-    } 
-    
-    if (res->size[arch] & (mask >> 1)) { /* if size have bits to one beside its biggest */
-      /* size is not a power of 2 */
-      /* alignment= next power of 2 after size */
-      res->alignment[arch] = (res->size[arch] & ~(mask >> 1)) << 1;
-      xbt_assert0(res->alignment[arch] != 0,
-		   "scalar type too large");
-      
-      res->aligned_size[arch] = aligned(res->size[arch], res->alignment[arch]);
-      xbt_assert0 (res->aligned_size[arch] >= 0,
-		    "scalar type too large");
-      
-    } else {
-      /* size is a power of 2, life is great */
-      res->alignment[arch]       = res->size[arch];
-      res->aligned_size[arch]    = res->size[arch];
-    }
-#endif     
   }
 
   res->category_code                 = e_gras_datadesc_type_cat_scalar;
@@ -152,27 +111,19 @@ gras_datadesc_type_t
 }
 
 
-/**
- * gras_dd_cat_field_free:
- *
- * Frees one struct or union field
- */
+/** Frees one struct or union field */
 void gras_dd_cat_field_free(void *f) {
   gras_dd_cat_field_t field = *(gras_dd_cat_field_t *)f;
   XBT_IN;
   if (field) {
     if (field->name) 
-      xbt_free(field->name);
-    xbt_free(field);
+      free(field->name);
+    free(field);
   }
   XBT_OUT;
 }
 
-/**
- * gras_datadesc_struct:
- *
- * Create a new struct and give a pointer to it 
- */
+/** \brief Declare a new structure description */
 gras_datadesc_type_t 
   gras_datadesc_struct(const char            *name) {
 
@@ -204,11 +155,7 @@ gras_datadesc_type_t
   return res;
 }
 
-/**
- * gras_datadesc_struct_append:
- *
- * Append a field to the struct
- */
+/** \brief Append a new field to a structure description */
 void
 gras_datadesc_struct_append(gras_datadesc_type_t struct_type,
 			    const char          *name,
@@ -270,6 +217,10 @@ gras_datadesc_struct_append(gras_datadesc_type_t struct_type,
   XBT_OUT;
 }
 
+/** \brief Close a structure description
+ * 
+ * No new field can be added afterward, and it is mandatory to close the structure before using it.
+ */
 void
 gras_datadesc_struct_close(gras_datadesc_type_t struct_type) {
   XBT_IN;
@@ -284,8 +235,8 @@ gras_datadesc_struct_close(gras_datadesc_type_t struct_type) {
 /**
  * gras_datadesc_cycle_set:
  * 
- * Tell GRAS that the pointers of the type described by @ddt may present
- * some loop, and that the cycle detection mecanism is needed.
+ * Tell GRAS that the pointers of the type described by ddt may present
+ * some loop, and that the cycle detection mechanism is needed.
  *
  * Note that setting this option when not needed have a rather bad effect 
  * on the performance (several times slower on big data).
@@ -294,11 +245,12 @@ void
 gras_datadesc_cycle_set(gras_datadesc_type_t ddt) {
   ddt->cycle = 1;
 }
+
 /**
  * gras_datadesc_cycle_unset:
  * 
- * Tell GRAS that the pointers of the type described by @ddt do not present
- * any loop and that cycle detection mecanism are not needed.
+ * Tell GRAS that the pointers of the type described by ddt do not present
+ * any loop and that cycle detection mechanism are not needed.
  * (default)
  */
 void
@@ -306,14 +258,10 @@ gras_datadesc_cycle_unset(gras_datadesc_type_t ddt) {
   ddt->cycle = 0;
 }
 
-/**
- * gras_datadesc_union:
- *
- * Create a new union and give a pointer to it 
- */
+/** \brief Declare a new union description */
 gras_datadesc_type_t 
-gras_datadesc_union(const char                   *name,
-		    gras_datadesc_type_cb_int_t   selector) {
+  gras_datadesc_union(const char                   *name,
+		      gras_datadesc_type_cb_int_t   selector) {
 
   gras_datadesc_type_t res;
   int arch;
@@ -350,15 +298,10 @@ gras_datadesc_union(const char                   *name,
   return res;
 }
 
-/**
- * gras_datadesc_union_append:
- *
- * Append a field to the union
- */
-void
-gras_datadesc_union_append(gras_datadesc_type_t  union_type,
-			   const char           *name,
-			   gras_datadesc_type_t  field_type) {
+/** \brief Append a new field to an union description */
+void gras_datadesc_union_append(gras_datadesc_type_t  union_type,
+				const char           *name,
+				gras_datadesc_type_t  field_type) {
 
   gras_dd_cat_field_t field;
   int arch;
@@ -392,15 +335,17 @@ gras_datadesc_union_append(gras_datadesc_type_t  union_type,
   }
 }
 
+
+/** \brief Close an union description 
+ *
+ * No new field can be added afterward, and it is mandatory to close the union before using it.
+ */
 void
 gras_datadesc_union_close(gras_datadesc_type_t union_type) {
    union_type->category.union_data.closed = 1;
 }
-/**
- * gras_datadesc_ref:
- *
- * Create a new ref to a fixed type and give a pointer to it 
- */
+
+/** \brief Declare a new type being a reference to the one passed in arg */
 gras_datadesc_type_t 
   gras_datadesc_ref(const char           *name,
 		    gras_datadesc_type_t  referenced_type) {
@@ -438,10 +383,11 @@ gras_datadesc_type_t
 
   return res;
 }
-/**
- * gras_datadesc_ref_generic:
- *
- * Create a new ref to a type given at use time, and give a pointer to it 
+/** \brief Declare a new type being a generic reference.
+ * 
+ * The callback passed in argument is to be used to select which type is currently used.
+ * So, when GRAS wants to send a generic reference, it passes the current data to the selector 
+ * callback and expects it to return the type description to use. 
  */
 gras_datadesc_type_t 
   gras_datadesc_ref_generic(const char                *name,
@@ -481,11 +427,7 @@ gras_datadesc_type_t
   return res;
 }
 
-/**
- * gras_datadesc_array_fixed:
- *
- * Create a new array and give a pointer to it 
- */
+/** \brief Declare a new type being an array of fixed size and content */
 gras_datadesc_type_t 
   gras_datadesc_array_fixed(const char           *name,
 			    gras_datadesc_type_t  element_type,
@@ -526,15 +468,11 @@ gras_datadesc_type_t
 
   return res;
 }
-/**
- * gras_datadesc_array_dyn:
- *
- * Create a new array and give a pointer to it 
- */
-gras_datadesc_type_t 
-  gras_datadesc_array_dyn(const char                  *name,
-			  gras_datadesc_type_t         element_type,
-			  gras_datadesc_type_cb_int_t  dynamic_size) {
+
+/** \brief Declare a new type being an array of fixed size, but accepting several content types. */
+gras_datadesc_type_t gras_datadesc_array_dyn(const char                 *name,
+					     gras_datadesc_type_t        element_type,
+					     gras_datadesc_type_cb_int_t dynamic_size) {
 
   gras_datadesc_type_t res;
   int arch;
@@ -576,9 +514,8 @@ gras_datadesc_type_t
   return res;
 }
 
-/**
- * gras_datadesc_ref_pop_arr:
- *
+/** \brief Declare a new type being an array which size can be found with \ref gras_cbps_i_pop 
+ * 
  * Most of the time, you want to include a reference in your structure which
  * is a pointer to a dynamic array whose size is fixed by another field of 
  * your structure.
@@ -613,7 +550,7 @@ gras_datadesc_type_t
   sprintf(name,"%s[]*",element_type->name);
   res = gras_datadesc_ref(name,res);
 
-  xbt_free(name);
+  free(name);
 
   return res;
 }
@@ -626,9 +563,6 @@ gras_datadesc_import_nws(const char           *name,
 }
 
 /**
- * gras_datadesc_cb_send:
- *
- * Add a pre-send callback to this datadesc.
  * (useful to push the sizes of the upcoming arrays, for example)
  */
 void gras_datadesc_cb_send (gras_datadesc_type_t          type,
@@ -636,16 +570,13 @@ void gras_datadesc_cb_send (gras_datadesc_type_t          type,
   type->send = send;
 }
 /**
- * gras_datadesc_cb_recv:
- *
- * Add a post-receive callback to this datadesc.
  * (useful to put the function pointers to the rigth value, for example)
  */
 void gras_datadesc_cb_recv(gras_datadesc_type_t          type,
 			   gras_datadesc_type_cb_void_t  recv) {
   type->recv = recv;
 }
-/**
+/*
  * gras_dd_find_field:
  * 
  * Returns the type descriptor of the given field. Abort on error.
@@ -677,9 +608,7 @@ static gras_datadesc_type_t
 }
 				  
 /**
- * gras_datadesc_cb_field_send:
- *
- * Add a pre-send callback to the given field of the datadesc (which must be a struct or union).
+ * The given datadesc must be a struct or union (abort if not).
  * (useful to push the sizes of the upcoming arrays, for example)
  */
 void gras_datadesc_cb_field_send (gras_datadesc_type_t          type,
@@ -691,10 +620,9 @@ void gras_datadesc_cb_field_send (gras_datadesc_type_t          type,
 }
 
 /**
- * gras_datadesc_cb_field_push:
- *
- * Add a pre-send callback to the given field resulting in its value to be pushed to
- * the stack of sizes. It must be a int, unsigned int, long int or unsigned long int.
+ * The value, which must be an int, unsigned int, long int or unsigned long int
+ * is pushed to the stacks of sizes and can then be retrieved with 
+ * \ref gras_datadesc_ref_pop_arr or directly with \ref gras_cbps_i_pop.
  */
 void gras_datadesc_cb_field_push (gras_datadesc_type_t  type,
 				  const char           *field_name) {
@@ -715,9 +643,7 @@ void gras_datadesc_cb_field_push (gras_datadesc_type_t  type,
    }
 }
 /**
- * gras_datadesc_cb_field_recv:
- *
- * Add a post-receive callback to the given field of the datadesc (which must be a struct or union).
+ * The given datadesc must be a struct or union (abort if not).
  * (useful to put the function pointers to the right value, for example)
  */
 void gras_datadesc_cb_field_recv(gras_datadesc_type_t          type,
@@ -728,9 +654,7 @@ void gras_datadesc_cb_field_recv(gras_datadesc_type_t          type,
    sub_type->recv = recv;
 }
 
-/**
- * gras_datadesc_free:
- *
+/*
  * Free a datadesc. Should only be called at xbt_exit. 
  */
 void gras_datadesc_free(gras_datadesc_type_t *type) {
@@ -763,8 +687,8 @@ void gras_datadesc_free(gras_datadesc_type_t *type) {
     /* datadesc was invalid. Killing it is like euthanasy, I guess */
     break;
   }
-  xbt_free((*type)->name);
-  xbt_free(*type);
+  free((*type)->name);
+  free(*type);
   type=NULL;
 }