1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
<html xmlns="http://www.w3.org/1999/xhtml">
4
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5
<title>SimGrid: Automatic parsing of data descriptions</title>
6
<link href="tabs.css" rel="stylesheet" type="text/css"/>
7
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
8
<link href="simgrid.css" rel="stylesheet" type="text/css">
11
<!-- Generated by Doxygen 1.7.4 -->
14
<table cellspacing="0" cellpadding="0">
16
<tr style="height: 56px;">
17
<td style="padding-left: 0.5em;">
18
<div id="projectname">SimGrid <span id="projectnumber">3.7.1</span></div>
19
<div id="projectbrief">Scalable simulation of distributed systems</div>
25
<div id="navrow1" class="tabs">
27
<li><a href="index.html"><span>Main Page</span></a></li>
28
<li class="current"><a href="modules.html"><span>Modules API</span></a></li>
29
<li class="current"><a href="use.html"><span>Using SimGrid</span></a></li>
30
<li><a href="http://gforge.inria.fr/projects/simgrid"><span>Forge</span></a></li>
31
<li><a href="http://simgrid.gforge.inria.fr/"><span>Website</span></a></li>
32
<li><a href="pages.html"><span>Documentation index</span></a></li>
33
<li><a href="FAQ.html"><span>FAQ</span></a></li>
35
<div class="tabs_group_use">
37
<li><a href="install.html"><span>Installing SimGrid</span></a></li>
38
<li class="current"><a href="modules.html"><span>Modules API</span></a></li>
39
<li><a href="options.html"><span>Options & configurations</span></a></li>
40
<li><a href="platform.html"><span>Platform Description</span></a></li>
41
<li><a href="tracing.html"><span>Tracing Simulations</span></a></li>
42
<li><a href="bindings.html"><span>Bindings</span></a></li>
43
<li><a href="pls.html"><span>Packet-Level Simulation</span></a></li>
50
<a href="#define-members">Defines</a> |
51
<a href="#func-members">Functions</a> </div>
52
<div class="headertitle">
53
<div class="title">Automatic parsing of data descriptions</div> </div>
54
<div class="ingroups"><a class="el" href="group__XBT__dd.html">Data description</a></div></div>
55
<div class="contents">
56
<table class="memberdecls">
57
<tr><td colspan="2"><h2><a name="define-members"></a>
58
Defines</h2></td></tr>
59
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga582dcac822dd60778b8c94de58d4f8b2"></a><!-- doxytag: member="XBT_dd_auto::XBT_DEFINE_TYPE" ref="ga582dcac822dd60778b8c94de58d4f8b2" args="(name, def)" -->
60
#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__XBT__dd__auto.html#ga582dcac822dd60778b8c94de58d4f8b2">XBT_DEFINE_TYPE</a>(name, def)</td></tr>
61
<tr><td class="mdescLeft"> </td><td class="mdescRight">Automatically parse C code. <br/></td></tr>
62
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga8603e34575afb07e3399e940b29caffc"></a><!-- doxytag: member="XBT_dd_auto::XBT_DEFINE_TYPE_EXTERN" ref="ga8603e34575afb07e3399e940b29caffc" args="" -->
63
#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__XBT__dd__auto.html#ga8603e34575afb07e3399e940b29caffc">XBT_DEFINE_TYPE_EXTERN</a></td></tr>
64
<tr><td class="mdescLeft"> </td><td class="mdescRight">if this symbol is defined, the <em>XBT_DEFINE_TYPE</em> symbols live in another file. <br/></td></tr>
65
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__XBT__dd__auto.html#gafdbc20cdd4b241eb9b560fb7ba715a5e">XBT_DEFINE_TYPE_LOCAL</a>(name, def)</td></tr>
66
<tr><td class="mdescLeft"> </td><td class="mdescRight">Define a symbol to be automatically parsed, disregarding <a class="el" href="group__XBT__dd__auto.html#ga8603e34575afb07e3399e940b29caffc" title="if this symbol is defined, the XBT_DEFINE_TYPE symbols live in another file.">XBT_DEFINE_TYPE_EXTERN</a>. <a href="#gafdbc20cdd4b241eb9b560fb7ba715a5e"></a><br/></td></tr>
67
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="gad252370e735aa0e3074915a638538a73"></a><!-- doxytag: member="XBT_dd_auto::xbt_datadesc_by_symbol" ref="gad252370e735aa0e3074915a638538a73" args="(name)" -->
68
#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__XBT__dd__auto.html#gad252370e735aa0e3074915a638538a73">xbt_datadesc_by_symbol</a>(name)</td></tr>
69
<tr><td class="mdescLeft"> </td><td class="mdescRight">Retrieve a datadesc which was previously parsed. <br/></td></tr>
70
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="gad5f58245365718043c805436acafcd1b"></a><!-- doxytag: member="XBT_dd_auto::XBT_ANNOTE" ref="gad5f58245365718043c805436acafcd1b" args="(key, val)" -->
71
#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__XBT__dd__auto.html#gad5f58245365718043c805436acafcd1b">XBT_ANNOTE</a>(key, val)</td></tr>
72
<tr><td class="mdescLeft"> </td><td class="mdescRight">Add an annotation to a type to be automatically parsed. <br/></td></tr>
73
<tr><td colspan="2"><h2><a name="func-members"></a>
74
Functions</h2></td></tr>
75
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga3e265dfcbdfeae45b43b46b39e594484"></a><!-- doxytag: member="XBT_dd_auto::xbt_datadesc_set_const" ref="ga3e265dfcbdfeae45b43b46b39e594484" args="(const char *name, int value)" -->
76
void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__XBT__dd__auto.html#ga3e265dfcbdfeae45b43b46b39e594484">xbt_datadesc_set_const</a> (const char *name, int value)</td></tr>
77
<tr><td class="mdescLeft"> </td><td class="mdescRight">Defines the value of a define to the datatype parsing infrastructure. <br/></td></tr>
79
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
80
<!-- DOXYGEN_NAVBAR_LABEL="Automatic parsing" --> <p>If you need to declare a new datatype, this is the simplest way to describe it to XBT. Simply enclose its type definition into a <a class="el" href="group__XBT__dd__auto.html#ga582dcac822dd60778b8c94de58d4f8b2">XBT_DEFINE_TYPE</a> macro call, and you're set. Here is an type declaration example: </p>
81
<div class="fragment"><pre class="fragment">XBT_DEFINE_TYPE(mytype,struct mytype {
84
});</pre></div><p> The type is then both copied verbatim into your source file and stored for further parsing. This allows you to let XBT parse the exact version you are actually using in your program. You can then retrieve the corresponding type description with <a class="el" href="group__XBT__dd__auto.html#gad252370e735aa0e3074915a638538a73">xbt_datadesc_by_symbol</a>. Don't worry too much for the performances, the type is only parsed once and a binary representation is stored and used in any subsequent calls.</p>
85
<p>If your structure contains any pointer, you have to explain XBT the size of the pointed array. This can be 1 in the case of simple references, or more in the case of regular arrays. For that, use the <a class="el" href="group__XBT__dd__auto.html#gad5f58245365718043c805436acafcd1b">XBT_ANNOTE</a> macro within the type declaration you are passing to <a class="el" href="group__XBT__dd__auto.html#ga582dcac822dd60778b8c94de58d4f8b2">XBT_DEFINE_TYPE</a>. This macro rewrites itself to nothing in the declaration (so they won't pollute the type definition copied verbatim into your code), and give some information to XBT about your pointer.</p>
86
<p>XBT_ANNOTE takes two arguments being the key name and the key value. For now, the only accepted key name is "size", to specify the length of the pointed array. It can either be:</p>
88
<li>the string "1" (without the quote),</li>
89
<li>the name of another field of the structure</li>
90
<li>a sort of computed expression for multidimensional arrays (see below -- pay attention to the warnings below).</li>
92
<p>Here is an example: </p>
93
<div class="fragment"><pre class="fragment">XBT_DEFINE_TYPE(s_clause,
96
struct s_array *father XBT_ANNOTE(size,1);
98
int *data XBT_ANNOTE(size,length);
101
int *matrix XBT_ANNOTE(size,rows*cols);
103
;)</pre></div><p> It specifies that the structure s_array contains six fields, that the <em>name</em> field is a classical null-terminated char* string (<a class="el" href="group__XBT__str.html#ga1537bf8b2602e0aeeb87032803a72389" title="Classical alias to (char*)">xbt_string_t</a> is just an helper type defined exactly to help the parsing macro to specify the semantic of the pointer), that <em>father</em> field is a simple reference, that the size of the array pointed by <em>data</em> is the <em>length</em> field, and that the <em>matrix</em> field is an arraywhich size is the result of <em>rows</em> times <em>cols</em>.</p>
104
<dl class="warning"><dt><b>Warning:</b></dt><dd>Since XBT_DEFINE_TYPE is a macro, you shouldn't put any comma in your type definition (comma separates macro args). For example, change <div class="fragment"><pre class="fragment">int a, b;</pre></div> to <div class="fragment"><pre class="fragment">int a;
105
int b;</pre></div></dd></dl>
106
<h2><a class="anchor" id="xbt_dd_define"></a>
107
#define and fixed size array</h2>
108
<p>If you want to exchange arrays which size is given at compilation time by a #defined constant, you need to keep XBT informed. It would be done the following way:</p>
109
<div class="fragment"><pre class="fragment">#define BLOCK_SIZE 32
110
XBT_DEFINE_TYPE(s_toto,
112
double data[BLOCK_SIZE];
115
void register_messages() {
116
xbt_datadesc_type_t toto_type;
118
xbt_datadesc_set_const("BLOCK_SIZE",BLOCK_SIZE);
119
toto_type = xbt_datadesc_by_symbol(s_toto);
120
}</pre></div><p>The form <code>xbt_datadesc_set_const("BLOCK_SIZE",BLOCK_SIZE);</code> ensures that when you change the definition of the constant, XBT keeps informed of the right value. Passing the numerical value of the constant as second argument would be a bad idea to that regard. Of course, the call to <a class="el" href="group__XBT__dd__auto.html#ga3e265dfcbdfeae45b43b46b39e594484" title="Defines the value of a define to the datatype parsing infrastructure.">xbt_datadesc_set_const()</a> should come before any <a class="el" href="group__XBT__dd__auto.html#gad252370e735aa0e3074915a638538a73" title="Retrieve a datadesc which was previously parsed.">xbt_datadesc_by_symbol()</a> containing references to it.</p>
121
<h2><a class="anchor" id="XBT_dd_multidim"></a>
122
Defining multidimentional arrays</h2>
123
<p>The mecanism for multidimensional arrays is known to be fragile and cumbersome. If you want to use it, you have to understand how it is implemented: the multiplication is performed using the sizes stack. In previous example, a <a class="el" href="group__XBT__dd__cb__simple.html#ga6545b0ef382856115f0c5803b1f054e4">xbt_datadesc_cb_push_int</a> callback is added to the <em>rows</em> field and a <a class="el" href="group__XBT__dd__cb__simple.html#ga0ee280a32ce28ccdedeae2a61ba3a5b0">xbt_datadesc_cb_push_int_mult</a> one is added to <em>cols</em>. So, when the structure is sent, the <em>rows</em> field push its value onto the stack, then the <em>cols</em> field retrieve this value from the stack, compute (and push) the multiplication value. The <em>matrix</em> field can then retrieve this value by poping the array. There is several ways for this to go wrong:</p>
125
<li>if the matrix field is placed before the sizes, the right value won't get pushed into the stack soon enough. Reorder your structure fields if needed.</li>
126
<li>if you write <a class="el" href="group__XBT__dd__auto.html#gad5f58245365718043c805436acafcd1b" title="Add an annotation to a type to be automatically parsed.">XBT_ANNOTE(size,cols*rows)</a>; in previous example (inverting rows and cols in annotation), <em>rows</em> will be given a <a class="el" href="group__XBT__dd__cb__simple.html#ga0ee280a32ce28ccdedeae2a61ba3a5b0">xbt_datadesc_cb_push_int_mult</a>. This cannot work since it will try to pop the value which will be pushed by <em>cols</em> <em>afterward</em>.</li>
127
<li>if you have more than one matrix in your structure, don't interleave the size. They are pushed/poped in the structure order.</li>
128
<li>if some of the sizes are used in more than one matrix, you cannot use this mecanism -- sorry.</li>
130
<p>If you cannot express your datadescs with this mechanism, you'll have to use the more advanced (and somehow complex) one described in the <a class="el" href="group__XBT__dd__cb__full.html">Data description with Callback Persistant State: Full featured interface</a>.</p>
131
<h2><a class="anchor" id="XBT_dd_multifile"></a>
132
Projects spanning over multiple files</h2>
133
<p>XBT_DEFINE_TYPE declares some symbols to work, it needs some special care when used in several files. In such case, you want the regular type definition in all files, but the xbt specific symbol defined in only one file. For example, consider the following xbt project sketch.</p>
134
<div class="fragment"><pre class="fragment">#include <xbt/datadesc.h>
136
XBT_DEFINE_TYPE(my_type,struct my_type {
142
int client(int argc, char *argv[]) {
146
int server(int argc, char *argv[]) {
148
}</pre></div><p>If you want to split this in two files (one for each kind of processes), you need to put the XBT_DEFINE_TYPE block in a separate header (so that each process kind see the associated C type definition). But then you cannot include this right away in all files because the extra symbols containing the XBT definition would be dupplicated.</p>
149
<p>You thus have to decide in which C file the symbols will live. In that file, include the header without restriction:</p>
150
<div class="fragment"><pre class="fragment">#include "my_header.h"
152
int client(int argc, char *argv[]) {
154
}</pre></div><p>And in the other files needing the C definitions without the extra XBT symbols, declare the symbol XBT_DEFINE_TYPE_EXTERN before loading xbt/datadesc.h:</p>
155
<div class="fragment"><pre class="fragment">#define XBT_DEFINE_TYPE_EXTERN
156
#include <xbt/datadesc.h>
157
#include "my_header.h"
159
int server(int argc, char *argv[]) {
161
}</pre></div><p>Sometimes, the situation is even more complicated: There is some shared messages that you want to see from every file, and some private messages that you want to be defined only in one C file. In that case, use the previous trick for common messages, and use <a class="el" href="group__XBT__dd__auto.html#gafdbc20cdd4b241eb9b560fb7ba715a5e" title="Define a symbol to be automatically parsed, disregarding XBT_DEFINE_TYPE_EXTERN.">XBT_DEFINE_TYPE_LOCAL</a> for the private messages.</p>
162
<p>For now, there is no way to have semi-private symbols (for example shared in all files of a library), sorry. Use functions as interface to your library instead of publishing directly the messages. </p>
163
<hr/><h2>Define Documentation</h2>
164
<a class="anchor" id="gafdbc20cdd4b241eb9b560fb7ba715a5e"></a><!-- doxytag: member="datadesc.h::XBT_DEFINE_TYPE_LOCAL" ref="gafdbc20cdd4b241eb9b560fb7ba715a5e" args="(name, def)" -->
165
<div class="memitem">
166
<div class="memproto">
167
<table class="memname">
169
<td class="memname">#define XBT_DEFINE_TYPE_LOCAL</td>
171
<td class="paramtype"> </td>
172
<td class="paramname">name, </td>
175
<td class="paramkey"></td>
177
<td class="paramtype"> </td>
178
<td class="paramname">def </td>
189
<p>Define a symbol to be automatically parsed, disregarding <a class="el" href="group__XBT__dd__auto.html#ga8603e34575afb07e3399e940b29caffc" title="if this symbol is defined, the XBT_DEFINE_TYPE symbols live in another file.">XBT_DEFINE_TYPE_EXTERN</a>. </p>
190
<p>Call this macro instead of <a class="el" href="group__XBT__dd__auto.html#ga582dcac822dd60778b8c94de58d4f8b2" title="Automatically parse C code.">XBT_DEFINE_TYPE</a> if you had to define <a class="el" href="group__XBT__dd__auto.html#ga8603e34575afb07e3399e940b29caffc" title="if this symbol is defined, the XBT_DEFINE_TYPE symbols live in another file.">XBT_DEFINE_TYPE_EXTERN</a> to load some external symbols, but if you now want to automatically parse the content of your private messages. </p>
201
<a href="index.html"><b>
202
Back to the main Simgrid Documentation page</b></a>
205
<small>The version of <a href="http://simgrid.gforge.inria.fr">SimGrid</a> documented here is v3.7.1.<br/>
206
Documentation of other versions can be found in their respective
207
archive files (directory doc/html).
210
<small>Generated by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border=0 width=110 height=53></a> </small>
added
removed
doc/html/group__XBT__dd__auto.html
