6 XBT is not an interface to describe your application, but rather a toolbox of features that are used everywhere in SimGrid. The code described in this page is not specific to any
7 of the existing interfaces, and it's used in all of them.
14 As introduced in :ref:`outcome_logs`, the SimGrid logging mechanism allows to configure at runtime the messages that should be displayed and those that should be omitted. Each
15 message produced in the code is given a category (denoting its topic) and a priority. Then at runtime, each category is given a threshold (only messages of priority higher than
16 that threshold are displayed), a layout (deciding how the messages in this category are formatted), and an appender (deciding what to do with the message: either print on stderr or
19 This section documents the provided API. To see how to configure these features at runtime, please refer to :ref:`logging_config`.
24 Typically, there will be a category for each module of the implementation, so that users can independently control the logging for each module.
25 Refer to the :ref:`logging_categories` section for a list of all existing categories in SimGrid.
27 .. c:macro:: XBT_LOG_NEW_CATEGORY(category, description)
29 Creates a new category that is not within any existing categories. It will be located right below the ``root`` category.
30 ``category`` must be a valid identifier (such as ``mycat``) with no quote or anything. It should also be unique over the whole binary.
31 ``description`` must be a string, between quotes.
33 .. c:macro:: XBT_LOG_NEW_SUBCATEGORY(category, parent_category, description)
35 Creates a new category under the provided ``parent_category``.
37 .. c:macro:: XBT_LOG_NEW_DEFAULT_CATEGORY(category, description)
39 Similar to :c:macro:`XBT_LOG_NEW_CATEGORY`, and the created category is the default one in the current source file.
41 .. c:macro:: XBT_LOG_NEW_DEFAULT_SUBCATEGORY(category, parent_category, description)
43 Similar to :c:macro:`XBT_LOG_NEW_SUBCATEGORY`, and the created category is the default one in the current source file.
45 .. c:macro:: XBT_LOG_EXTERNAL_CATEGORY(category)
47 Make an external category (i.e., a category declared in another source file) visible from this source file.
48 In each source file, at most one one category can be the default one.
50 .. c:macro:: XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(category)
52 Use an external category as default category in this source file.
60 .. c:macro:: XBT_CRITICAL(format_string, parameters...)
62 Report a fatal error to the default category.
64 .. c:macro:: XBT_ERROR(format_string, parameters...)
66 Report an error to the default category.
68 .. c:macro:: XBT_WARN(format_string, parameters...)
70 Report a warning or an important information to the default category.
72 .. c:macro:: XBT_INFO(format_string, parameters...)
74 Report an information of regular importance to the default category.
76 .. c:macro:: XBT_VERB(format_string, parameters...)
78 Report a verbose information to the default category.
80 .. c:macro:: XBT_DEBUG(format_string, parameters...)
82 Report a debug-only information to the default category.
84 For each of the logging macros, the first parameter must be a printf-like format string, and the subsequent parameters must match this format. If you compile with the -Wall option,
85 the compiler will warn you for unmatched arguments, such as passing a pointer while the format string expects an integer. Using this option is usually a good idea.
87 Here is an example: ``XBT_WARN("Values are: %d and '%s'", 5, "oops");``
89 .. c:macro:: XBT_IN(format_string, parameters...)
91 Report that the execution flow enters a given function (which name is displayed automatically).
93 .. c:macro:: XBT_OUT(format_string, parameters...)
95 Report that the execution flow exits a given function (which name is displayed automatically).
97 .. c:macro:: XBT_HERE(format_string, parameters...)
99 Report that the execution flow reaches a given location.
104 .. c:macro:: XBT_CCRITICAL(category, format_string, parameters...)
106 Report a fatal error to the specified ``category``.
108 .. c:macro:: XBT_CERROR(category, format_string, parameters...)
110 Report an error to the specified ``category``.
112 .. c:macro:: XBT_CWARN(category, format_string, parameters...)
114 Report a warning or an important information to the specified ``category``.
116 .. c:macro:: XBT_CINFO(category, format_string, parameters...)
118 Report an information of regular importance to the specified ``category``.
120 .. c:macro:: XBT_CVERB(category, format_string, parameters...)
122 Report a verbose information to the specified ``category``.
124 .. c:macro:: XBT_CDEBUG(category, format_string, parameters...)
126 Report a debug-only information to the specified ``category``.
128 Of course, the specified category must be visible from this source file, either because it was created there (e.g. with :c:macro:`XBT_LOG_NEW_CATEGORY`) or because it was made
129 visible with :c:macro:`XBT_LOG_EXTERNAL_CATEGORY`.
134 .. c:macro:: XBT_LOG_ISENABLED(category, priority)
136 Returns true if that category displays the messages of that priority. It's useful to compute a value that is used only in the logging, such as the textual representation of a
139 The specified priority must be one of ``xbt_log_priority_trace``, ``xbt_log_priority_debug``, ``xbt_log_priority_verbose``, ``xbt_log_priority_info``,
140 ``xbt_log_priority_warning``, ``xbt_log_priority_error`` or ``xbt_log_priority_critical``.
142 .. c:function:: void xbt_log_control_set(const char* setting)
144 Sets the provided ``setting`` as if it was passed in a ``--log`` command-line parameter.
146 You should not use any of the macros which name starts with '_'.
148 .. include:: ../build/log_categories.rst
157 /* create a category and a default subcategory */
158 XBT_LOG_NEW_CATEGORY(VSS);
159 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(SA, VSS);
162 /* Now set the parent's priority. (the string would typically be a runtime option) */
163 xbt_log_control_set("SA.thresh:info");
165 /* This request is enabled, because WARNING >= INFO. */
166 XBT_CWARN(VSS, "Low fuel level.");
168 /* This request is disabled, because DEBUG < INFO. */
169 XBT_CDEBUG(VSS, "Starting search for nearest gas station.");
171 /* The default category SA inherits its priority from VSS. Thus,
172 the following request is enabled because INFO >= INFO. */
173 XBT_INFO("Located nearest gas station.");
175 /* This request is disabled, because DEBUG < INFO. */
176 XBT_DEBUG("Exiting gas station search");
182 This module is highly optimized. Messages that will not be displayed are not even built. For example, using ``XBT_DEBUG`` in a category that turns debug messages off only costs a
183 single integer comparison at runtime, and the parameters are not even evaluated.
185 You can even specify a compile-time threshold that will completely remove every logging below the specified priority. Passing ``-DNDEBUG`` to cmake disables every logging of
186 priority below INFO while ``-DNLOG`` removes any logging at compile time. Note that using this feature may hinder the stability of SimGrid, as we consider the logs to be fast
187 enough to not thoughtfully test the case where they are removed at compile time.
192 As SimGrid used to be written in pure C, it used to rely on custom data containers such as dynamic arrays and dictionnaries. Nowadays, the standard library of
193 C++ is used internally, but some part of the interface still rely on the old containers, that are thus still available.
197 You should probably not start a new project using these data structures, as we will :ref:`deprecate them from SimGrid <deprecation_policy>`
198 as soon as possible. Better implementations exist out there anyway, in particular if you're not writting pure C code.
200 .. doxygentypedef:: xbt_dynar_t
201 .. doxygentypedef:: const_xbt_dynar_t
203 Creation and destruction
204 ========================
206 .. doxygenfunction:: xbt_dynar_new
207 .. doxygenfunction:: xbt_dynar_free
208 .. doxygenfunction:: xbt_dynar_free_container
210 Dynars as regular arrays
211 ========================
213 .. doxygenfunction:: xbt_dynar_get_cpy
214 .. doxygenfunction:: xbt_dynar_insert_at
215 .. doxygenfunction:: xbt_dynar_remove_at
216 .. doxygenfunction:: xbt_dynar_member
217 .. doxygenfunction:: xbt_dynar_sort
222 .. doxygenfunction:: xbt_dynar_is_empty
223 .. doxygenfunction:: xbt_dynar_length
224 .. doxygenfunction:: xbt_dynar_reset
229 .. doxygenfunction:: xbt_dynar_push
230 .. doxygenfunction:: xbt_dynar_pop
231 .. doxygenfunction:: xbt_dynar_unshift
232 .. doxygenfunction:: xbt_dynar_shift
233 .. doxygenfunction:: xbt_dynar_map
235 Direct content manipulation
236 ===========================
238 Those functions do not retrieve the content, but only their address.
240 .. doxygenfunction:: xbt_dynar_set_at_ptr
241 .. doxygenfunction:: xbt_dynar_get_ptr
242 .. doxygenfunction:: xbt_dynar_insert_at_ptr
243 .. doxygenfunction:: xbt_dynar_push_ptr
244 .. doxygenfunction:: xbt_dynar_pop_ptr
249 While the other functions use a memcpy to retrieve the content into the user provided area, those ones use a
250 regular affectation. It only works for scalar values, but should be a little faster.
252 .. doxygendefine:: xbt_dynar_get_as
253 .. doxygendefine:: xbt_dynar_set_as
255 .. doxygendefine:: xbt_dynar_getlast_as
256 .. doxygendefine:: xbt_dynar_getfirst_as
257 .. doxygendefine:: xbt_dynar_push_as
258 .. doxygendefine:: xbt_dynar_pop_as
260 Iterating over Dynars
261 =====================
263 .. doxygendefine:: xbt_dynar_foreach
265 Example with scalar values
266 ==========================
270 xbt_dynar_t d = xbt_dynar_new(sizeof(int), nullptr);
272 /* 1. Populate the dynar */
273 xbt_dynar_t d = xbt_dynar_new(sizeof(int), nullptr);
274 for (int cpt = 0; cpt < NB_ELEM; cpt++) {
275 xbt_dynar_push_as(d, int, cpt); /* This is faster (and possible only with scalars) */
276 /* xbt_dynar_push(d,&cpt); This would also work */
277 xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
280 /* 2. Traverse manually the dynar */
281 for (cursor = 0; cursor < NB_ELEM; cursor++) {
282 int* iptr = (int*)xbt_dynar_get_ptr(d, cursor);
283 /* 1. Populate further the dynar */
284 for (int cpt = 0; cpt < NB_ELEM; cpt++) {
285 xbt_dynar_insert_at(d, cpt, &cpt);
286 xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
289 /* 3. Traverse the dynar */
291 xbt_dynar_foreach(d, cursor, cpt) {
292 xbt_test_assert(cursor == (unsigned int) cpt, "The retrieved value is not the same than the injected one (%u!=%d)", cursor, cpt);
295 /* 4. Reset the values */
296 for (int i = 0; i < NB_ELEM; i++)
297 *(int*)xbt_dynar_get_ptr(d, i) = i;
299 /* 5. Shift all the values */
300 for (int i = 0; i < NB_ELEM; i++) {
302 xbt_dynar_shift(d, &val);
304 // the dynar is empty after shifting all values
306 /* 5. Free the resources */
309 Example with pointed values
310 ===========================
314 xbt_dynar_t d = xbt_dynar_new(sizeof(char*), &xbt_free_ref);
316 /// Push/shift example
317 for (int i = 0; i < NB_ELEM; i++) {
318 char * val = xbt_strdup("hello");
319 xbt_dynar_push(d, &val);
321 for (int i = 0; i < NB_ELEM; i++) {
323 xbt_dynar_shift(d, &val);
324 REQUIRE("hello" == val);
329 /// Unshift, traverse and pop example
330 d = xbt_dynar_new(sizeof(char**), &xbt_free_ref);
331 for (int i = 0; i < NB_ELEM; i++) {
332 std::string val = std::to_string(i);
333 s1 = xbt_strdup(val.c_str());
334 xbt_dynar_unshift(d, &s1);
336 /* 2. Traverse the dynar with the macro */
337 xbt_dynar_foreach (d, iter, s1) {
338 std::string val = std::to_string(NB_ELEM - iter - 1);
339 REQUIRE(s1 == val); // The retrieved value is not the same than the injected one
341 /* 3. Traverse the dynar with the macro */
342 for (int i = 0; i < NB_ELEM; i++) {
343 std::string val = std::to_string(i);
344 xbt_dynar_pop(d, &s2);
345 REQUIRE(s2 == val); // The retrieved value is not the same than the injected one
348 /* 4. Free the resources */