Simple manual data description

Typedefs
typedef struct s_xbt_cbps *	xbt_cbps_t
	Opaque type describing a type description callback persistent state.
typedef void(*	xbt_datadesc_type_cb_void_t )(xbt_datadesc_type_t typedesc, xbt_cbps_t vars, void *data)
	Prototype of type callbacks returning nothing.
typedef int(*	xbt_datadesc_type_cb_int_t )(xbt_datadesc_type_t typedesc, xbt_cbps_t vars, void *data)
	Prototype of type callbacks returning an int.
typedef xbt_datadesc_type_t(*	xbt_datadesc_selector_t )(xbt_datadesc_type_t typedesc, xbt_cbps_t vars, void *data)
	Prototype of type callbacks selecting a type.
Functions
xbt_datadesc_type_t	xbt_datadesc_struct (const char *name)
	Declare a new structure description.
void	xbt_datadesc_struct_append (xbt_datadesc_type_t struct_type, const char *name, xbt_datadesc_type_t field_type)
	Append a new field to a structure description.
void	xbt_datadesc_struct_close (xbt_datadesc_type_t struct_type)
	Close a structure description.
xbt_datadesc_type_t	xbt_datadesc_union (const char *name, xbt_datadesc_type_cb_int_t selector)
	Declare a new union description.
void	xbt_datadesc_union_append (xbt_datadesc_type_t union_type, const char *name, xbt_datadesc_type_t field_type)
	Append a new field to an union description.
void	xbt_datadesc_union_close (xbt_datadesc_type_t union_type)
	Close an union description.
xbt_datadesc_type_t	xbt_datadesc_ref (const char *name, xbt_datadesc_type_t referenced_type)
	Declare a new type being a reference to the one passed in arg.
xbt_datadesc_type_t	xbt_datadesc_copy (const char *name, xbt_datadesc_type_t copied_type)
	Copy a type under another name.
xbt_datadesc_type_t	xbt_datadesc_ref_generic (const char *name, xbt_datadesc_selector_t selector)
	Declare a new type being a generic reference.
xbt_datadesc_type_t	xbt_datadesc_array_fixed (const char *name, xbt_datadesc_type_t element_type, long int fixed_size)
	Declare a new type being an array of fixed size and content.
xbt_datadesc_type_t	xbt_datadesc_array_dyn (const char *name, xbt_datadesc_type_t element_type, xbt_datadesc_type_cb_int_t dynamic_size)
	Declare a new type being an array of fixed size, but accepting several content types.
xbt_datadesc_type_t	xbt_datadesc_ref_pop_arr (xbt_datadesc_type_t element_type)
	Declare a new type being an array which size can be found with xbt_cbps_i_pop.
xbt_datadesc_type_t	xbt_datadesc_dynar (xbt_datadesc_type_t elm_t, void_f_pvoid_t free_func)
	Declare a new type being a dynar in which each elements are of the given type.
void	xbt_datadesc_cycle_set (xbt_datadesc_type_t type)
	Specify that this type may contain cycles.
void	xbt_datadesc_cycle_unset (xbt_datadesc_type_t type)
	Specify that this type do not contain any cycles (default)
void	xbt_datadesc_cb_send (xbt_datadesc_type_t type, xbt_datadesc_type_cb_void_t pre)
	Add a pre-send callback to this datadesc.
void	xbt_datadesc_cb_recv (xbt_datadesc_type_t type, xbt_datadesc_type_cb_void_t post)
	Add a post-receive callback to this datadesc.
void	xbt_datadesc_cb_field_send (xbt_datadesc_type_t type, const char *field_name, xbt_datadesc_type_cb_void_t pre)
	Add a pre-send callback to the given field of the datadesc.
void	xbt_datadesc_cb_field_recv (xbt_datadesc_type_t type, const char *field_name, xbt_datadesc_type_cb_void_t post)
	Add a post-receive callback to the given field of the datadesc.
void	xbt_datadesc_cb_field_push (xbt_datadesc_type_t type, const char *field_name)
	Add a pre-send callback to the given field resulting in its value to be pushed.
void	xbt_datadesc_cb_field_push_multiplier (xbt_datadesc_type_t type, const char *field_name)
	Add a pre-send callback to the given field resulting in its value multiplied to any previously pushed value and then pushed back.
const char *	xbt_datadesc_get_name (xbt_datadesc_type_t ddt)
	Returns the name of a datadescription.
int	xbt_datadesc_get_id (xbt_datadesc_type_t ddt)
	Returns the identifier of a datadescription.

---

Detailed Description

Here are the functions to use if you want to declare your description manually. The function names should be self-explanatory in most cases.

You can add callbacks to the datatypes doing any kind of action you may want. Usually, pre-send callbacks are used to prepare the type expedition while post-receive callbacks are used to fix any issue after the receive.

If your types are dynamic, you'll need to add some extra callback. For example, there is a specific callback for the string type which is in charge of computing the length of the char array. This is done with the cbps mechanism, explained in next section.

If your types may contain pointer cycle, you must specify it to XBT using the xbt_datadesc_cycle_set.

Example:

 typedef struct {
   unsigned char c1;
   unsigned long int l1;
   unsigned char c2;
   unsigned long int l2;
 } mystruct;
 [...]
  my_type=xbt_datadesc_struct("mystruct");
  xbt_datadesc_struct_append(my_type,"c1", xbt_datadesc_by_name("unsigned char"));
  xbt_datadesc_struct_append(my_type,"l1", xbt_datadesc_by_name("unsigned long"));
  xbt_datadesc_struct_append(my_type,"c2", xbt_datadesc_by_name("unsigned char"));
  xbt_datadesc_struct_append(my_type,"l2", xbt_datadesc_by_name("unsigned long int"));
  xbt_datadesc_struct_close(my_type);

  my_type=xbt_datadesc_ref("mystruct*", xbt_datadesc_by_name("mystruct"));

  [Use my_type to send pointers to mystruct data]

---

Function Documentation

void xbt_datadesc_struct_close

(

xbt_datadesc_type_t

struct_type

)

Close a structure description.

No new field can be added afterward, and it is mandatory to close the structure before using it.

void xbt_datadesc_union_close

(

xbt_datadesc_type_t

union_type

)

Close an union description.

No new field can be added afterward, and it is mandatory to close the union before using it.

xbt_datadesc_type_t xbt_datadesc_copy	(	const char *	name,
		xbt_datadesc_type_t	copied
	)

Copy a type under another name.

This may reveal useful to circumvent parsing macro limitations

xbt_datadesc_type_t xbt_datadesc_ref_generic	(	const char *	name,
		xbt_datadesc_selector_t	selector
	)

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 XBT 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.

xbt_datadesc_type_t xbt_datadesc_ref_pop_arr

(

xbt_datadesc_type_t

element_type

)

Declare a new type being an array which size can be found with xbt_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.

This case pops up so often that this function was created to take care of this case. It creates a dynamic array type whose size is poped from the current cbps, and then create a reference to it.

The name of the created datatype will be the name of the element type, with '[]*' appended to it.

Then to use it, you just have to make sure that your structure pre-callback does push the size of the array in the cbps (using xbt_cbps_i_push), and you are set.

But be remember that this is a stack. If you have two different pop_arr, you should push the second one first, so that the first one is on the top of the list when the first field gets transfered.

xbt_datadesc_type_t xbt_datadesc_dynar	(	xbt_datadesc_type_t	elm_t,
		void_f_pvoid_t	free_func
	)

Declare a new type being a dynar in which each elements are of the given type.

The type gets registered under the name "dynar(%s)_s", where s is the name of the subtype. For example, a dynar of doubles will be called "dynar(double)_s" and a dynar of dynar of strings will be called "dynar(dynar(string)_s)_s".

Parameters:

elm_t,:	the datadesc of the elements
free_func,:	the function to use to free the elements when the dynar gets freed

void xbt_datadesc_cycle_set

(

xbt_datadesc_type_t

ddt

)

Specify that this type may contain cycles.

xbt_datadesc_cycle_set:

Tell XBT 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).

void xbt_datadesc_cycle_unset

(

xbt_datadesc_type_t

ddt

)

Specify that this type do not contain any cycles (default)

xbt_datadesc_cycle_unset:

Tell XBT that the pointers of the type described by ddt do not present any loop and that cycle detection mechanism are not needed. (default)

void xbt_datadesc_cb_send	(	xbt_datadesc_type_t	type,
		xbt_datadesc_type_cb_void_t	send
	)

Add a pre-send callback to this datadesc.

(useful to push the sizes of the upcoming arrays, for example)

void xbt_datadesc_cb_recv	(	xbt_datadesc_type_t	type,
		xbt_datadesc_type_cb_void_t	recv
	)

Add a post-receive callback to this datadesc.

(useful to put the function pointers to the rigth value, for example)

void xbt_datadesc_cb_field_send	(	xbt_datadesc_type_t	type,
		const char *	field_name,
		xbt_datadesc_type_cb_void_t	send
	)

Add a pre-send callback to the given field of the datadesc.

The given datadesc must be a struct or union (abort if not). (useful to push the sizes of the upcoming arrays, for example)

void xbt_datadesc_cb_field_recv	(	xbt_datadesc_type_t	type,
		const char *	field_name,
		xbt_datadesc_type_cb_void_t	recv
	)

Add a post-receive callback to the given field of the datadesc.

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 xbt_datadesc_cb_field_push	(	xbt_datadesc_type_t	type,
		const char *	field_name
	)

Add a pre-send callback to the given field resulting in its value to be pushed.

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 xbt_datadesc_ref_pop_arr or directly with xbt_cbps_i_pop.

void xbt_datadesc_cb_field_push_multiplier	(	xbt_datadesc_type_t	type,
		const char *	field_name
	)

Add a pre-send callback to the given field resulting in its value multiplied to any previously pushed value and then pushed back.

Any previously pushed value is poped and the field value is multiplied to it. The result is then pushed back into the stack of sizes. It can then be retrieved with xbt_datadesc_ref_pop_arr or directly with xbt_cbps_i_pop.

The field must be an int, unsigned int, long int or unsigned long int.

const char* xbt_datadesc_get_name

(

xbt_datadesc_type_t

ddt

)

Returns the name of a datadescription.

This is mainly to debug

int xbt_datadesc_get_id

(

xbt_datadesc_type_t

ddt

)

Returns the identifier of a datadescription.

This is mainly to debug