src/modules.doc

   1 /** \defgroup SimGrid_API  API of SimGrid */
   2
   3 /** \defgroup XBT_API      XBT (eXtended Bundle of tools)
   4     \ingroup SimGrid_API
   5     \brief
   6     The core toolbox of SimGrid, containing usefull datatypes, portability
   7     support and so on.
   8 */
   9 /** \defgroup XBT_ground   Grounding features of the XBT (logging and error reporting)
  10     \ingroup XBT_API
  11 */
  12     /** \defgroup XBT_log Logging support.
  13      *  \ingroup XBT_ground
  14      *  \brief A generic logging facility in the spirit of log4j
  15      *
  16      *  This section describes the API to the log functions used
  17      *  everywhere in this project.
  18
  19 <h3>Overview</h3>
  20
  21 This is an adaptation of the log4c project, which is dead upstream, and
  22 which I was given the permission to fork under the LGPL licence by the
  23 authors. log4c itself was loosely based on the Apache project's Log4J,
  24 Log4CC, etc. project. Because C is not object oriented, a lot had to change.
  25
  26 There is 3 main concepts: category, priority and appender. These three
  27 concepts work together to enable developers to log messages according to
  28 message type and priority, and to control at runtime how these messages are
  29 formatted and where they are reported.
  30
  31 <h3>Category hierarchy</h3>
  32
  33 The first and foremost advantage of any logging API over plain printf()
  34 resides in its ability to disable certain log statements while allowing
  35 others to print unhindered. This capability assumes that the logging space,
  36 that is, the space of all possible logging statements, is categorized
  37 according to some developer-chosen criteria.
  38
  39 This observation led to choosing category as the central concept of the
  40 system. Every category is declared by providing a name and an optional
  41 parent. If no parent is explicitly named, the root category, LOG_ROOT_CAT is
  42 the category's parent.
  43
  44 A category is created by a macro call at the top level of a file.  A
  45 category can be created with any one of the following macros:
  46
  47  - \ref XBT_LOG_NEW_CATEGORY(MyCat); Create a new root
  48  - \ref XBT_LOG_NEW_SUBCATEGORY(MyCat, ParentCat);
  49     Create a new category being child of the category ParentCat
  50  - \ref XBT_LOG_NEW_DEFAULT_CATEGORY(MyCat);
  51     Like XBT_LOG_NEW_CATEGORY, but the new category is the default one
  52       in this file
  53  -  \ref XBT_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, ParentCat);
  54     Like XBT_LOG_NEW_SUBCATEGORY, but the new category is the default one
  55       in this file
  56
  57 The parent cat can be defined in the same file or in another file (in
  58 which case you want to use the \ref XBT_LOG_EXTERNAL_CATEGORY macro to make
  59 it visible in the current file), but each category may have only one
  60 definition.
  61
  62 Typically, there will be a Category for each module and sub-module, so you
  63 can independently control logging for each module.
  64
  65 <h3>Priority</h3>
  66
  67 A category may be assigned a threshold priorty. The set of priorites are
  68 defined by the \ref e_xbt_log_priority_t enum. All logging request under
  69 this priority will be discarded.
  70
  71 If a given category is not assigned a threshold priority, then it inherits
  72 one from its closest ancestor with an assigned threshold. To ensure that all
  73 categories can eventually inherit a threshold, the root category always has
  74 an assigned threshold priority.
  75
  76 Logging requests are made by invoking a logging macro on a category.  All of
  77 the macros have a printf-style format string followed by arguments. If you
  78 compile with the -Wall option, gcc will warn you for unmatched arguments, ie
  79 when you pass a pointer to a string where an integer was specified by the
  80 format. This is usualy a good idea.
  81
  82 Because most C compilers do not support vararg macros, there is a version of
  83 the macro for any number of arguments from 0 to 6. The macro name ends with
  84 the total number of arguments.
  85
  86 Here is an example of the most basic type of macro. This is a logging
  87 request with priority <i>warning</i>.
  88
  89 <code>CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5,
  90 "oops");</code>
  91
  92 A logging request is said to be enabled if its priority is higher than or
  93 equal to the threshold priority of its category. Otherwise, the request is
  94 said to be disabled. A category without an assigned priority will inherit
  95 one from the hierarchy.
  96
  97 It is possible to use any non-negative integer as a priority. If, as in the
  98 example, one of the standard priorites is used, then there is a convenience
  99 macro that is typically used instead. For example, the above example is
 100 equivalent to the shorter:
 101
 102 <code>CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops");</code>
 103
 104 <h3>Default category</h3>
 105
 106 If \ref XBT_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, Parent) or
 107 \ref XBT_LOG_NEW_DEFAULT_CATEGORY(MyCat) is used to create the
 108 category, then the even shorter form can be used:
 109
 110 <code>WARN3("Values are: %d and '%s'", 5, "oops");</code>
 111
 112 Only one default category can be created per file, though multiple
 113 non-defaults can be created and used.
 114
 115 <h3>Example</h3>
 116
 117 Here is a more complete example:
 118
 119 \verbatim
 120 #include "xbt/log.h"
 121
 122 / * create a category and a default subcategory * /
 123 XBT_LOG_NEW_CATEGORY(VSS);
 124 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(SA, VSS);
 125
 126 int main() {
 127        / * Now set the parent's priority.  (the string would typcially be a runtime option) * /
 128        xbt_log_control_set("SA.thresh=3");
 129
 130        / * This request is enabled, because WARNING &gt;= INFO. * /
 131        CWARN2(VSS, "Low fuel level.");
 132
 133        / * This request is disabled, because DEBUG &lt; INFO. * /
 134        CDEBUG2(VSS, "Starting search for nearest gas station.");
 135
 136        / * The default category SA inherits its priority from VSS. Thus,
 137           the following request is enabled because INFO &gt;= INFO.  * /
 138        INFO1("Located nearest gas station.");
 139
 140        / * This request is disabled, because DEBUG &lt; INFO. * /
 141        DEBUG1("Exiting gas station search");
 142 }
 143 \endverbatim
 144
 145 <h3>Configuration</h3>
 146 Configuration is typically done during program initialization by invoking
 147 the xbt_log_control_set() method. The control string passed to it typically
 148 comes from the command line. Look at the documentation for that function for
 149 the format of the control string.
 150
 151 Any SimGrid program can furthermore be configured at run time by passing a
 152 --xbt-log argument on the command line (--gras-log, --msg-log and
 153 --surf-log are synonyms). You can provide several of those arguments to
 154 change the setting of several categories.
 155
 156 <h3>Performance</h3>
 157
 158 Clever design insures efficiency. Except for the first invocation, a
 159 disabled logging request requires an a single comparison of a static
 160 variable to a constant.
 161
 162 There is also compile time constant, \ref XBT_LOG_STATIC_THRESHOLD, which
 163 causes all logging requests with a lower priority to be optimized to 0 cost
 164 by the compiler. By setting it to gras_log_priority_infinite, all logging
 165 requests are statically disabled and cost nothing. Released executables
 166 might be compiled with
 167 \verbatim-DXBT_LOG_STATIC_THRESHOLD=gras_log_priority_infinite\endverbatim
 168
 169 <h3>Appenders</h3>
 170
 171 Each category has an optional appender. An appender is a pointer to a
 172 structure which starts with a pointer to a doAppend() function. DoAppend()
 173 prints a message to a log.
 174
 175 When a category is passed a message by one of the logging macros, the
 176 category performs the following actions:
 177
 178   - if the category has an appender, the message is passed to the
 179     appender's doAppend() function,
 180   - if 'willLogToParent' is true for the category, the message is passed
 181     to the category's parent.
 182
 183 By default, only the root category have an appender, and 'willLogToParent'
 184 is true for any other category. This situation causes all messages to be
 185 logged by the root category's appender.
 186
 187 The default appender function currently prints to stderr, and no other one
 188 exist, even if more would be needed, like the one able to send the logs to a
 189 remote dedicated server, or other ones offering different output formats.
 190 This is on our TODO list for quite a while now, but your help would be
 191 welcome here.
 192
 193 <h3>Misc and Caveats</h3>
 194
 195 Do not use any of the macros that start with '_'.
 196
 197 Log4J has a 'rolling file appender' which you can select with a run-time
 198 option and specify the max file size. This would be a nice default for
 199 non-kernel applications.
 200
 201 Careful, category names are global variables.
 202
 203 */
 204
 205
 206     /** \defgroup XBT_error Error tracking support.
 207      *  \ingroup XBT_ground
 208      *  \brief This section describes a set of macros used to handle errors easily.
 209      */
 210 /** \defgroup XBT_structs  Datatypes defined in the XBT
 211     \ingroup XBT_API
 212 */
 213     /** \defgroup XBT_dict A generic dictionnary
 214      *  \ingroup XBT_structs
 215      *  \brief This section describes the API to a dictionnary structure that
 216      *  associates as string to a void* key. It is not a hash table and the
 217      *  internal data-structure rather looks like a tree.
 218      */
 219     /** \defgroup XBT_dynar A generic dynamic array
 220      *  \ingroup XBT_structs
 221      *  \brief This section describes the API to generic dynamic array (vector).
 222      */
 223     /** \defgroup XBT_fifo A generic workqueue
 224      *  \ingroup XBT_structs
 225      *  \brief This section describes the API to generic workqueue. These functions
 226      *   provide the same kind of functionnality as dynamic arrays but in time O(1).
 227      *   However these functions use malloc/free a way too much often.
 228      */
 229     /** \defgroup XBT_set A generic set datatype
 230      *  \ingroup XBT_structs
 231      *  \brief A data container consisting in \ref XBT_dict and \ref XBT_dynar
 232      */
 233     /** \defgroup XBT_swag A specific set datatype
 234      *  \ingroup XBT_structs
 235      *  \brief a O(1) set based on linked lists
 236      *
 237      *  Warning, this module is done to be efficient and performs tons of
 238      *  cast and dirty things. So avoid using it unless you really know
 239      *  what you are doing. It is basically a fifo but with restrictions so that
 240      *  it can be used as a set. Any operation (add, remove, belongs) is O(1) and
 241      *  no call to malloc/free is done.
 242      */
 243     /** \defgroup XBT_heap A generic heap data structure
 244      *  \ingroup XBT_structs
 245      *  \brief This section describes the API to generic heap with O(log(n)) access.
 246      */
 247
 248 /** \defgroup XBT_port     Portability support defined in the XBT (you shouldn't use it directly)
 249     \ingroup XBT_API
 250 */
 251     /** \defgroup XBT_context User-level context library
 252      *  \ingroup XBT_port
 253      *  \brief This section describes how to use high-level functions
 254      *  (as opposed to <tt>setjump/longjmp</tt>) to schedule non-preemptible
 255      *  threads.
 256      */
 257     /** \defgroup XBT_sysdep All system dependency
 258      *  \ingroup XBT_port
 259      *  \brief This section describes many macros/functions that can serve as
 260      *  an OS abstraction.
 261      */
 262
 263
 264 /** \defgroup SURF_API       SURF (simulator kernel)
 265  *  \ingroup SimGrid_API
 266  *  \brief Kernel of all the simulators used in SimGrid, and associated models.
 267  *
 268
 269  * SURF provides the core functionnalities to simulate a virtual
 270  * platform. It is very low-level and is not intended to be used as
 271  * such but rather to serve as a basis for higher-level simulators.
 272  * We're still working on it and the structure is a little bit complex.
 273  * So we'll document it only when we'll be completely satisfied of
 274  * the way it is organized.
 275  *
 276  * It is where platform models are encoded. If you need a model that is not
 277  * encoded yet, please tell me (<arnaud.legrand@imag.fr>) and we'll see if
 278  * it is feasible or not (hopefully it should be but who knows).
 279  *
 280  * Please note that as it is not really intended for public use, this module
 281  * is only partially documented.
 282  */
 283
 284 /** \defgroup MSG_API      MSG
 285  *  \ingroup SimGrid_API
 286  *  \brief Simple programming environment
 287  *
 288  *  MSG was the first distributed programming environment provided within
 289  *  SimGrid. While almost realistic, it remains quite simple (simplistic?).
 290  *
 291  *  You should use this model if you want to study some heuristics for a
 292  *  given problem you don't really want to implement. If you want to get a
 293  *  real implementation of your solution, have a look at the \ref GRAS_API
 294  *  programming environment. If you want to study an existing MPI program,
 295  *  have a look at the \ref SMPI_API one. If none of those programming
 296  *  environments fits your needs, you may consider implementing your own
 297  *  directly on top of \ref SURF_API (but you probably want to contact us
 298  *  before).
 299  *
 300  */
 301     /** \defgroup m_datatypes_management MSG Data Types
 302      *  \ingroup MSG_API
 303      *  \brief This section describes the different datatypes provided by MSG.
 304      *
 305      */
 306
 307     /** \defgroup m_process_management Management Functions of Agents
 308      *  \ingroup MSG_API
 309      *  \brief This section describes the agent structure of MSG
 310      *  (#m_process_t) and the functions for managing it.
 311      *
 312      *  We need to simulate many independent scheduling decisions, so
 313      *  the concept of <em>process</em> is at the heart of the
 314      *  simulator. A process may be defined as a <em>code</em>, with
 315      *  some <em>private data</em>, executing in a <em>location</em>.
 316      *  \see m_process_t
 317      */
 318
 319     /** \defgroup m_host_management    Management Functions of Hosts
 320      *  \ingroup MSG_API
 321      *  \brief This section describes the host structure of MSG
 322      * (#m_host_t) and the functions for managing it.
 323      *
 324      *  A <em>location</em> (or <em>host</em>) is any possible place where
 325      *  a process may run. Thus it may be represented as a
 326      *  <em>physical resource with computing capabilities</em>, some
 327      *  <em>mailboxes</em> to enable running process to communicate with
 328      *  remote ones, and some <em>private data</em> that can be only
 329      *  accessed by local process.
 330      *  \see m_host_t
 331      */
 332
 333     /** \defgroup m_task_management    Management Functions of Tasks
 334      *  \ingroup MSG_API
 335      *  \brief This section describes the task structure of MSG
 336      *  (#m_task_t) and the functions for managing it.
 337      *
 338      *  Since most scheduling algorithms rely on a concept of task
 339      *  that can be either <em>computed</em> locally or
 340      *  <em>transferred</em> on another processor, it seems to be the
 341      *  right level of abstraction for our purposes. A <em>task</em>
 342      *  may then be defined by a <em>computing amount</em>, a
 343      *  <em>message size</em> and some <em>private data</em>.
 344      */
 345
 346     /** \defgroup msg_gos_functions    MSG Operating System Functions
 347      *  \ingroup MSG_API
 348      *  \brief This section describes the functions that can be used
 349      *  by an agent for handling some task.
 350      */
 351
 352     /** \defgroup m_channel_management    Understanding channels
 353      *  \ingroup MSG_API
 354      *  \brief This section briefly describes the channel notion of MSG
 355      *  (#m_channel_t).
 356      *
 357      *  For convenience, the simulator provides the notion of channel
 358      *  that is close to the tag notion in MPI. A channel is not a
 359      *  socket. It doesn't need to be opened neither closed. It rather
 360      *  corresponds to the ports opened on the different machines.
 361      */
 362
 363     /** \defgroup msg_easier_life      Platform and Application management
 364      *  \ingroup MSG_API
 365      *  \brief This section describes functions to manage the platform creation
 366      *  and the application deployment. You should also have a look at
 367      *  \ref MSG_examples  to have an overview of their usage.
 368      */
 369
 370     /** \defgroup msg_simulation       MSG simulation Functions
 371      *  \ingroup MSG_API
 372      *  \brief This section describes the functions you need to know to
 373      *  set up a simulation. You should have a look at \ref MSG_examples
 374      *  to have an overview of their usage.
 375      */
 376
 377 /** \defgroup GRAS_API      GRAS
 378  *  \ingroup SimGrid_API
 379  *  \brief Realistic programming environment (Grid Reality And Simulation)
 380  *
 381  *  GRAS provide a complete API to implement distributed application on top
 382  *  of heterogeneous plateforms. In addition to the SimGrid implementation
 383  *  of this interface (allowing you to work on your application within the
 384  *  comfort of the simulator), an implementation suited to real platforms is
 385  *  also provided (allowing you to really use your application once you're
 386  *  done with developing it).
 387  *
 388  *  GRAS thus constitute a complete grid application developement framework,
 389  *  encompassing both developer helping tools (the simulator and associated
 390  *  tools) and an efficient while portable execution runtime.
 391  *
 392  *  You should use this programming environment if you want to develop real
 393  *  applications, ie if the final result of your work is a program which
 394  *  may eventually be distributed.
 395  *  If you just want to study some heuristics for a given problem you don't
 396  *  want to implement really (ie, if your result would be a theorem), have a
 397  *  look at the \ref MSG_API one.
 398  *  If you want to study an existing MPI program, have a look at the
 399  *  \ref SMPI_API one.
 400  *  If none of those programming environments fits your needs, you may
 401  *  consider implementing your own directly on top of \ref SURF_API (but you
 402  *  probably want to contact us before).
 403  *
 404  *  The user visibile features tend to offer several kind of functionnalities:
 405  *   - <b>Communication facilities</b>: Exchanging messages between peers
 406  *   - <b>Virtualization</b>: Running both on top of the simulator and on
 407  *     top of real platforms, and portability support.
 408  */
 409
 410    /** \defgroup GRAS_dd     Data description
 411     *  \ingroup GRAS_API
 412     *  \brief Describing data to be exchanged (Communication facility)
 413     */
 414
 415    /** \defgroup GRAS_sock   Sockets
 416     *  \ingroup GRAS_API
 417     *  \brief Open/close sockets, and get info on peer (Communication facility).
 418     */
 419
 420    /** \defgroup GRAS_msg    Messages
 421     *  \ingroup GRAS_API
 422     *  \brief Defining messages and callbacks, and sending/receiving messages (Communication facility).
 423     */
 424
 425    /** \defgroup GRAS_globals Globals
 426     *  \ingroup GRAS_API
 427     *  \brief Handling global variables so that it works on simulator (Virtualization).
 428     *
 429     *  In GRAS, using globals is forbidden since the "processes" will
 430     *  sometimes run as a thread inside the same process (namely, in
 431     *  simulation mode). So, you have to put all globals in a structure, and
 432     *  let GRAS handle it.
 433     *
 434     *  Use the \ref gras_userdata_new macro to create a new user data (or malloc it
 435     *   and use \ref gras_userdata_set yourself), and \ref gras_userdata_get to
 436     *   retrive a reference to it.
 437     */
 438
 439    /** \defgroup GRAS_virtu Syscalls
 440     *  \ingroup GRAS_API
 441     *  \brief System call abstraction layer (Virtualization).
 442     */
 443
 444
 445 /** \defgroup SMPI_API      SMPI
 446  *  \ingroup SimGrid_API
 447  *  \brief Programming environment for the simulation of MPI applications
 448  *
 449  *  Once implemented, this programming environment will allow you to study
 450  *  within the simulator any MPI application without having to modify them
 451  *  for that. In other words, it will constitute an emulation solution for
 452  *  parallel codes.
 453  *
 454  *  You should use this programming environment of the SimGrid suite if you
 455  *  want to study existing MPI applications.
 456  *  If you want to work on a distributed application, have a look at the
 457  *  \ref GRAS_API environment.
 458  *  If you want to study some heuristics for a given problem (and if your
 459  *  goal is to produce theorems, not code), have a look at the \ref MSG_API
 460  *  environment.
 461  *  If none of those programming environments fits your needs, you may
 462  *  consider implementing your own directly on top of \ref SURF_API (but you
 463  *  probably want to contact us before).
 464  *
 465  */