-/** \defgroup SimGrid_API API of SimGrid */
+/**
+ \defgroup SimGrid_API API of SimGrid */
/** \defgroup XBT_API XBT (eXtended Bundle of tools)
- \ingroup SimGrid_API
- \brief
- The core toolbox of SimGrid, containing usefull datatypes, portability
- support and so on.
-*/
-/** \defgroup XBT_ground Grounding features of the XBT (logging and error reporting)
- \ingroup XBT_API
+ \ingroup SimGrid_API
+ \brief The core toolbox of SimGrid, containing usefull datatypes,
+ portability support and so on.
*/
- /** \defgroup XBT_log Logging support.
- * \ingroup XBT_ground
- * \brief A generic logging facility in the spirit of log4j
- *
- * This section describes the API to the log functions used
- * everywhere in this project.
-
-<h3>Overview</h3>
+/** \defgroup XBT_ground Grounding features of the XBT (logging and error reporting)
+ \ingroup XBT_API */
+/** \addtogroup XBT_log
+ \ingroup XBT_ground */
+/** \addtogroup XBT_error
+ \ingroup XBT_ground */
+
+/** \defgroup XBT_structs Datatypes defined in the XBT
+ \ingroup XBT_API */
+/** \addtogroup XBT_dict
+ \ingroup XBT_structs */
+/** \addtogroup XBT_dynar
+ \ingroup XBT_structs */
+/** \addtogroup XBT_fifo
+ \ingroup XBT_structs */
+/** \addtogroup XBT_set
+ \ingroup XBT_structs */
+/** \addtogroup XBT_swag
+ \ingroup XBT_structs */
+/** \addtogroup XBT_heap
+ \ingroup XBT_structs */
-This is an adaptation of the log4c project, which is dead upstream, and
-which I was given the permission to fork under the LGPL licence by the
-authors. log4c itself was loosely based on the Apache project's Log4J,
-Log4CC, etc. project. Because C is not object oriented, a lot had to change.
-
-There is 3 main concepts: category, priority and appender. These three
-concepts work together to enable developers to log messages according to
-message type and priority, and to control at runtime how these messages are
-formatted and where they are reported.
-
-<h3>Category hierarchy</h3>
-
-The first and foremost advantage of any logging API over plain printf()
-resides in its ability to disable certain log statements while allowing
-others to print unhindered. This capability assumes that the logging space,
-that is, the space of all possible logging statements, is categorized
-according to some developer-chosen criteria.
-
-This observation led to choosing category as the central concept of the
-system. Every category is declared by providing a name and an optional
-parent. If no parent is explicitly named, the root category, LOG_ROOT_CAT is
-the category's parent.
-
-A category is created by a macro call at the top level of a file. A
-category can be created with any one of the following macros:
-
- - \ref XBT_LOG_NEW_CATEGORY(MyCat); Create a new root
- - \ref XBT_LOG_NEW_SUBCATEGORY(MyCat, ParentCat);
- Create a new category being child of the category ParentCat
- - \ref XBT_LOG_NEW_DEFAULT_CATEGORY(MyCat);
- Like XBT_LOG_NEW_CATEGORY, but the new category is the default one
- in this file
- - \ref XBT_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, ParentCat);
- Like XBT_LOG_NEW_SUBCATEGORY, but the new category is the default one
- in this file
-
-The parent cat can be defined in the same file or in another file (in
-which case you want to use the \ref XBT_LOG_EXTERNAL_CATEGORY macro to make
-it visible in the current file), but each category may have only one
-definition.
-
-Typically, there will be a Category for each module and sub-module, so you
-can independently control logging for each module.
-
-<h3>Priority</h3>
-
-A category may be assigned a threshold priorty. The set of priorites are
-defined by the \ref e_xbt_log_priority_t enum. All logging request under
-this priority will be discarded.
-
-If a given category is not assigned a threshold priority, then it inherits
-one from its closest ancestor with an assigned threshold. To ensure that all
-categories can eventually inherit a threshold, the root category always has
-an assigned threshold priority.
-
-Logging requests are made by invoking a logging macro on a category. All of
-the macros have a printf-style format string followed by arguments. If you
-compile with the -Wall option, gcc will warn you for unmatched arguments, ie
-when you pass a pointer to a string where an integer was specified by the
-format. This is usualy a good idea.
-
-Because most C compilers do not support vararg macros, there is a version of
-the macro for any number of arguments from 0 to 6. The macro name ends with
-the total number of arguments.
-
-Here is an example of the most basic type of macro. This is a logging
-request with priority <i>warning</i>.
-
-<code>CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5,
-"oops");</code>
-
-A logging request is said to be enabled if its priority is higher than or
-equal to the threshold priority of its category. Otherwise, the request is
-said to be disabled. A category without an assigned priority will inherit
-one from the hierarchy.
-
-It is possible to use any non-negative integer as a priority. If, as in the
-example, one of the standard priorites is used, then there is a convenience
-macro that is typically used instead. For example, the above example is
-equivalent to the shorter:
-
-<code>CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops");</code>
-
-<h3>Default category</h3>
-
-If \ref XBT_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, Parent) or
-\ref XBT_LOG_NEW_DEFAULT_CATEGORY(MyCat) is used to create the
-category, then the even shorter form can be used:
-
-<code>WARN3("Values are: %d and '%s'", 5, "oops");</code>
-
-Only one default category can be created per file, though multiple
-non-defaults can be created and used.
-
-<h3>Example</h3>
-
-Here is a more complete example:
-
-\verbatim
-#include "xbt/log.h"
-
-/ * create a category and a default subcategory * /
-XBT_LOG_NEW_CATEGORY(VSS);
-XBT_LOG_NEW_DEFAULT_SUBCATEGORY(SA, VSS);
-
-int main() {
- / * Now set the parent's priority. (the string would typcially be a runtime option) * /
- xbt_log_control_set("SA.thresh=3");
-
- / * This request is enabled, because WARNING >= INFO. * /
- CWARN2(VSS, "Low fuel level.");
-
- / * This request is disabled, because DEBUG < INFO. * /
- CDEBUG2(VSS, "Starting search for nearest gas station.");
-
- / * The default category SA inherits its priority from VSS. Thus,
- the following request is enabled because INFO >= INFO. * /
- INFO1("Located nearest gas station.");
-
- / * This request is disabled, because DEBUG < INFO. * /
- DEBUG1("Exiting gas station search");
-}
-\endverbatim
-
-<h3>Configuration</h3>
-Configuration is typically done during program initialization by invoking
-the xbt_log_control_set() method. The control string passed to it typically
-comes from the command line. Look at the documentation for that function for
-the format of the control string.
-
-Any SimGrid program can furthermore be configured at run time by passing a
---xbt-log argument on the command line (--gras-log, --msg-log and
---surf-log are synonyms). You can provide several of those arguments to
-change the setting of several categories.
-
-<h3>Performance</h3>
-
-Clever design insures efficiency. Except for the first invocation, a
-disabled logging request requires an a single comparison of a static
-variable to a constant.
-
-There is also compile time constant, \ref XBT_LOG_STATIC_THRESHOLD, which
-causes all logging requests with a lower priority to be optimized to 0 cost
-by the compiler. By setting it to gras_log_priority_infinite, all logging
-requests are statically disabled and cost nothing. Released executables
-might be compiled with
-\verbatim-DXBT_LOG_STATIC_THRESHOLD=gras_log_priority_infinite\endverbatim
-
-<h3>Appenders</h3>
-
-Each category has an optional appender. An appender is a pointer to a
-structure which starts with a pointer to a doAppend() function. DoAppend()
-prints a message to a log.
-
-When a category is passed a message by one of the logging macros, the
-category performs the following actions:
-
- - if the category has an appender, the message is passed to the
- appender's doAppend() function,
- - if 'willLogToParent' is true for the category, the message is passed
- to the category's parent.
-
-By default, only the root category have an appender, and 'willLogToParent'
-is true for any other category. This situation causes all messages to be
-logged by the root category's appender.
-
-The default appender function currently prints to stderr, and no other one
-exist, even if more would be needed, like the one able to send the logs to a
-remote dedicated server, or other ones offering different output formats.
-This is on our TODO list for quite a while now, but your help would be
-welcome here.
-
-<h3>Misc and Caveats</h3>
-
-Do not use any of the macros that start with '_'.
-
-Log4J has a 'rolling file appender' which you can select with a run-time
-option and specify the max file size. This would be a nice default for
-non-kernel applications.
-
-Careful, category names are global variables.
-
-*/
-
-
- /** \defgroup XBT_error Error tracking support.
- * \ingroup XBT_ground
- * \brief This section describes a set of macros used to handle errors easily.
- */
-/** \defgroup XBT_structs Datatypes defined in the XBT
- \ingroup XBT_API
-*/
- /** \defgroup XBT_dict A generic dictionnary
- * \ingroup XBT_structs
- * \brief This section describes the API to a dictionnary structure that
- * associates as string to a void* key. It is not a hash table and the
- * internal data-structure rather looks like a tree.
- */
- /** \defgroup XBT_dynar A generic dynamic array
- * \ingroup XBT_structs
- * \brief This section describes the API to generic dynamic array (vector).
- */
- /** \defgroup XBT_fifo A generic workqueue
- * \ingroup XBT_structs
- * \brief This section describes the API to generic workqueue. These functions
- * provide the same kind of functionnality as dynamic arrays but in time O(1).
- * However these functions use malloc/free a way too much often.
- */
- /** \defgroup XBT_set A generic set datatype
- * \ingroup XBT_structs
- * \brief A data container consisting in \ref XBT_dict and \ref XBT_dynar
- */
- /** \defgroup XBT_swag A specific set datatype
- * \ingroup XBT_structs
- * \brief a O(1) set based on linked lists
- *
- * Warning, this module is done to be efficient and performs tons of
- * cast and dirty things. So avoid using it unless you really know
- * what you are doing. It is basically a fifo but with restrictions so that
- * it can be used as a set. Any operation (add, remove, belongs) is O(1) and
- * no call to malloc/free is done.
- */
- /** \defgroup XBT_heap A generic heap data structure
- * \ingroup XBT_structs
- * \brief This section describes the API to generic heap with O(log(n)) access.
- */
-
-/** \defgroup XBT_port Portability support defined in the XBT (you shouldn't use it directly)
- \ingroup XBT_API
-*/
- /** \defgroup XBT_context User-level context library
- * \ingroup XBT_port
- * \brief This section describes how to use high-level functions
- * (as opposed to <tt>setjump/longjmp</tt>) to schedule non-preemptible
- * threads.
- */
- /** \defgroup XBT_sysdep All system dependency
- * \ingroup XBT_port
- * \brief This section describes many macros/functions that can serve as
- * an OS abstraction.
- */
-
+/** \defgroup XBT_port Portability support defined in the XBT
+ (you shouldn't use it directly)
+ \ingroup XBT_API */
+/** \addtogroup XBT_context
+ \ingroup XBT_port */
+/** \addtogroup XBT_sysdep
+ \ingroup XBT_port */
/** \defgroup SURF_API SURF (simulator kernel)
- * \ingroup SimGrid_API
- * \brief Kernel of all the simulators used in SimGrid, and associated models.
- *
+ \ingroup SimGrid_API
+ \brief Kernel of all the simulators used in SimGrid, and associated models.
- * SURF provides the core functionnalities to simulate a virtual
- * platform. It is very low-level and is not intended to be used as
- * such but rather to serve as a basis for higher-level simulators.
- * We're still working on it and the structure is a little bit complex.
- * So we'll document it only when we'll be completely satisfied of
- * the way it is organized.
- *
- * It is where platform models are encoded. If you need a model that is not
- * encoded yet, please tell me (<arnaud.legrand@imag.fr>) and we'll see if
- * it is feasible or not (hopefully it should be but who knows).
- *
- * Please note that as it is not really intended for public use, this module
- * is only partially documented.
- */
+ SURF provides the core functionnalities to simulate a virtual
+ platform. It is very low-level and is not intended to be used as
+ such but rather to serve as a basis for higher-level simulators.
+ We're still working on it and the structure is a little bit
+ complex. So we'll document it only when we'll be completely satisfied of
+ the way it is organized.
+
+ It is where platform models are encoded. If you need a model that is not
+ encoded yet, please tell me (<arnaud.legrand@imag.fr>) and we'll
+ see if it is feasible or not (hopefully it should be but who knows).
+
+ Please note that as it is not really intended for public use,
+ this module is only partially documented.
+*/
/** \defgroup MSG_API MSG
- * \ingroup SimGrid_API
- * \brief Simple programming environment
- *
- * MSG was the first distributed programming environment provided within
- * SimGrid. While almost realistic, it remains quite simple (simplistic?).
- *
- * You should use this model if you want to study some heuristics for a
- * given problem you don't really want to implement. If you want to get a
- * real implementation of your solution, have a look at the \ref GRAS_API
- * programming environment. If you want to study an existing MPI program,
- * have a look at the \ref SMPI_API one. If none of those programming
- * environments fits your needs, you may consider implementing your own
- * directly on top of \ref SURF_API (but you probably want to contact us
- * before).
- *
- */
- /** \defgroup m_datatypes_management MSG Data Types
- * \ingroup MSG_API
- * \brief This section describes the different datatypes provided by MSG.
- *
- */
-
- /** \defgroup m_process_management Management Functions of Agents
- * \ingroup MSG_API
- * \brief This section describes the agent structure of MSG
- * (#m_process_t) and the functions for managing it.
- *
- * We need to simulate many independent scheduling decisions, so
- * the concept of <em>process</em> is at the heart of the
- * simulator. A process may be defined as a <em>code</em>, with
- * some <em>private data</em>, executing in a <em>location</em>.
- * \see m_process_t
- */
-
- /** \defgroup m_host_management Management Functions of Hosts
- * \ingroup MSG_API
- * \brief This section describes the host structure of MSG
- * (#m_host_t) and the functions for managing it.
- *
- * A <em>location</em> (or <em>host</em>) is any possible place where
- * a process may run. Thus it may be represented as a
- * <em>physical resource with computing capabilities</em>, some
- * <em>mailboxes</em> to enable running process to communicate with
- * remote ones, and some <em>private data</em> that can be only
- * accessed by local process.
- * \see m_host_t
- */
-
- /** \defgroup m_task_management Management Functions of Tasks
- * \ingroup MSG_API
- * \brief This section describes the task structure of MSG
- * (#m_task_t) and the functions for managing it.
- *
- * Since most scheduling algorithms rely on a concept of task
- * that can be either <em>computed</em> locally or
- * <em>transferred</em> on another processor, it seems to be the
- * right level of abstraction for our purposes. A <em>task</em>
- * may then be defined by a <em>computing amount</em>, a
- * <em>message size</em> and some <em>private data</em>.
- */
-
- /** \defgroup msg_gos_functions MSG Operating System Functions
- * \ingroup MSG_API
- * \brief This section describes the functions that can be used
- * by an agent for handling some task.
- */
-
- /** \defgroup m_channel_management Understanding channels
- * \ingroup MSG_API
- * \brief This section briefly describes the channel notion of MSG
- * (#m_channel_t).
- *
- * For convenience, the simulator provides the notion of channel
- * that is close to the tag notion in MPI. A channel is not a
- * socket. It doesn't need to be opened neither closed. It rather
- * corresponds to the ports opened on the different machines.
- */
+ \ingroup SimGrid_API
+ \brief Simple programming environment
+
+ MSG was the first distributed programming environment provided within
+ SimGrid. While almost realistic, it remains quite simple (simplistic?).
- /** \defgroup msg_easier_life Platform and Application management
- * \ingroup MSG_API
- * \brief This section describes functions to manage the platform creation
- * and the application deployment. You should also have a look at
- * \ref MSG_examples to have an overview of their usage.
- */
+ \section MSG_who Who should use this (and who shouldn't)
+
+ You should use this model if you want to study some heuristics for a
+ given problem you don't really want to implement. If you want to get a
+ real implementation of your solution, have a look at the \ref GRAS_API
+ programming environment. If you want to study an existing MPI program,
+ have a look at the \ref SMPI_API one. If none of those programming
+ environments fits your needs, you may consider implementing your own
+ directly on top of \ref SURF_API (but you probably want to contact us
+ before).
+*/
+/** \addtogroup m_datatypes_management
+ \ingroup MSG_API */
+/** \addtogroup m_process_management
+ \ingroup MSG_API */
+/** \addtogroup m_host_management
+ \ingroup MSG_API */
+/** \addtogroup m_task_management
+ \ingroup MSG_API */
+/** \addtogroup msg_gos_functions
+ \ingroup MSG_API */
+/** \addtogroup m_channel_management
+ \ingroup MSG_API */
+/** \addtogroup msg_easier_life
+ \ingroup MSG_API */
+/** \addtogroup msg_simulation
+ \ingroup MSG_API */
- /** \defgroup msg_simulation MSG simulation Functions
- * \ingroup MSG_API
- * \brief This section describes the functions you need to know to
- * set up a simulation. You should have a look at \ref MSG_examples
- * to have an overview of their usage.
- */
/** \defgroup GRAS_API GRAS
- * \ingroup SimGrid_API
- * \brief Realistic programming environment (Grid Reality And Simulation)
- *
- * GRAS provide a complete API to implement distributed application on top
- * of heterogeneous plateforms. In addition to the SimGrid implementation
- * of this interface (allowing you to work on your application within the
- * comfort of the simulator), an implementation suited to real platforms is
- * also provided (allowing you to really use your application once you're
- * done with developing it).
- *
- * GRAS thus constitute a complete grid application developement framework,
- * encompassing both developer helping tools (the simulator and associated
- * tools) and an efficient while portable execution runtime.
- *
- * You should use this programming environment if you want to develop real
- * applications, ie if the final result of your work is a program which
- * may eventually be distributed.
- * If you just want to study some heuristics for a given problem you don't
- * want to implement really (ie, if your result would be a theorem), have a
- * look at the \ref MSG_API one.
- * If you want to study an existing MPI program, have a look at the
- * \ref SMPI_API one.
- * If none of those programming environments fits your needs, you may
- * consider implementing your own directly on top of \ref SURF_API (but you
- * probably want to contact us before).
- *
- * The user visibile features tend to offer several kind of functionnalities:
- * - <b>Communication facilities</b>: Exchanging messages between peers
- * - <b>Virtualization</b>: Running both on top of the simulator and on
- * top of real platforms, and portability support.
- */
+ \ingroup SimGrid_API
+ \brief Realistic programming environment (Grid Reality And Simulation)
+
+ GRAS provide a complete API to implement distributed application on top
+ of heterogeneous plateforms. In addition to the SimGrid implementation
+ of this interface (allowing you to work on your application within the
+ comfort of the simulator), an implementation suited to real platforms is
+ also provided (allowing you to really use your application once you're
+ done with developing it).
+
+ GRAS thus constitute a complete grid application developement framework,
+ encompassing both developer helping tools (the simulator and associated
+ tools) and an efficient while portable execution runtime.
+
+ \section GRAS_who Who should use this (and who shouldn't)
+
+ You should use this programming environment if you want to develop real
+ applications, ie if the final result of your work is a program which
+ may eventually be distributed.
+ If you just want to study some heuristics for a given problem you don't
+ want to implement really (ie, if your result would be a theorem), have a
+ look at the \ref MSG_API one.
+ If you want to study an existing MPI program, have a look at the
+ \ref SMPI_API one.
+ If none of those programming environments fits your needs, you may
+ consider implementing your own directly on top of \ref SURF_API (but you
+ probably want to contact us before).
+
+ \section GRAS_funct Offered functionnalities
+ - <b>Communication facilities</b>: Exchanging messages between peers
+ - \ref GRAS_dd: any data which may transit on the network must be
+ described beforehand so that GRAS can handle the platform
+ heterogeneity and convert them if needed.
+ - \ref GRAS_sock: this is how to open a communication channel to
+ other processes, and retrive information about them.
+ - \ref GRAS_msg: communications are message oriented. You have to
+ describe all possible messages and their payload beforehand, and
+ can then attach callbacks to the arrival of a given kind of message.
+ - <b>Virtualization</b>: Running both on top of the simulator and on
+ top of real platforms, and portability support.
+ - \ref GRAS_globals: The use of globals is forbidden since the
+ "processes" are threads in simulation mode. \n
+ This is how to let GRAS handle your globals properly.
+ - \ref GRAS_cond: How to declare specific code for the simulation mode
+ or for the real mode.
+ - \ref GRAS_virtu: You naturally don't want to call the
+ gettimeofday(2) function in simulation mode since it would give
+ you the time on the host running the simulation, not the time in
+ the simulated world (you are belonging to).\n
+ This a system call virtualization layer, which also acts as a
+ portability layer.
+
+ \section GRAS_todo TODO
+ Documentation related:
+ - Add an example to the \ref GRAS_msg section, at least
+ - Document examples/gras/gras_stub_generator utility and how to deal
+ with the fact that programs must have a main in RL and not in SG.
+ - Document example/gras/ping as it uses almost all of the GRAS
+ features.
- /** \defgroup GRAS_dd Data description
- * \ingroup GRAS_API
- * \brief Describing data to be exchanged (Communication facility)
- */
-
- /** \defgroup GRAS_sock Sockets
- * \ingroup GRAS_API
- * \brief Open/close sockets, and get info on peer (Communication facility).
- */
-
- /** \defgroup GRAS_msg Messages
- * \ingroup GRAS_API
- * \brief Defining messages and callbacks, and sending/receiving messages (Communication facility).
- */
-
- /** \defgroup GRAS_globals Globals
- * \ingroup GRAS_API
- * \brief Handling global variables so that it works on simulator (Virtualization).
- *
- * In GRAS, using globals is forbidden since the "processes" will
- * sometimes run as a thread inside the same process (namely, in
- * simulation mode). So, you have to put all globals in a structure, and
- * let GRAS handle it.
- *
- * Use the \ref gras_userdata_new macro to create a new user data (or malloc it
- * and use \ref gras_userdata_set yourself), and \ref gras_userdata_get to
- * retrive a reference to it.
- */
+ Code related: too long to be written here. See the TODO file
+
+ @{
+*/
- /** \defgroup GRAS_virtu Syscalls
- * \ingroup GRAS_API
- * \brief System call abstraction layer (Virtualization).
- */
+ /** \defgroup GRAS_dd Data description */
+ /** \defgroup GRAS_sock Sockets */
+ /** \defgroup GRAS_msg Messages */
+
+ /** \defgroup GRAS_globals Globals */
+ /** \defgroup GRAS_cond Conditional execution */
+ /** \defgroup GRAS_virtu Syscalls */
+/** @} */
/** \defgroup SMPI_API SMPI
- * \ingroup SimGrid_API
- * \brief Programming environment for the simulation of MPI applications
- *
- * Once implemented, this programming environment will allow you to study
- * within the simulator any MPI application without having to modify them
- * for that. In other words, it will constitute an emulation solution for
- * parallel codes.
- *
- * You should use this programming environment of the SimGrid suite if you
- * want to study existing MPI applications.
- * If you want to work on a distributed application, have a look at the
- * \ref GRAS_API environment.
- * If you want to study some heuristics for a given problem (and if your
- * goal is to produce theorems, not code), have a look at the \ref MSG_API
- * environment.
- * If none of those programming environments fits your needs, you may
- * consider implementing your own directly on top of \ref SURF_API (but you
- * probably want to contact us before).
- *
+ \ingroup SimGrid_API
+ \brief Programming environment for the simulation of MPI applications
+
+ Once implemented, this programming environment will allow you to study
+ within the simulator any MPI application without having to modify them
+ for that. In other words, it will constitute an emulation solution for
+ parallel codes.
+
+ \section SMPI_who Who should use this (and who shouldn't)
+
+ You should use this programming environment of the SimGrid suite if you
+ want to study existing MPI applications.
+ If you want to work on a distributed application, have a look at the
+ \ref GRAS_API environment.
+ If you want to study some heuristics for a given problem (and if your
+ goal is to produce theorems, not code), have a look at the \ref MSG_API
+ environment.
+ If none of those programming environments fits your needs, you may
+ consider implementing your own directly on top of \ref SURF_API (but you
+ probably want to contact us before).
+
*/
