-/** \defgroup SimGrid_API API of SimGrid */
+/**
+ \defgroup SimGrid_API API of SimGrid */
-/** \defgroup XBT_API API of the toolbox (FIFO, hashtables, macros...)
- \ingroup SimGrid_API
+/** \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_context User-level context library
- * \ingroup XBT_API
- * \brief This section describes how to use high-level functions
- * (as opposed to <c>setjump/longjmp</c>) to schedule non-preemptible
- * threads.
- */
- /** \defgroup XBT_dict A generic dictionnary
- * \ingroup XBT_API
- * \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_API
- * \brief This section describes the API to generic dynamic array (vector).
- */
- /** \defgroup XBT_error Error tracking support.
- * \ingroup XBT_API
- * \brief This section describes a set of macros used to handle errors easily.
- */
- /** \defgroup XBT_fifo A generic workqueue
- * \ingroup XBT_API
- * \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_swag A specific set datatype
- * \ingroup XBT_API
- * \brief 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_API
- * \brief This section describes the API to generic heap.
- */
- /** \defgroup XBT_log A generic logging facility in the spirit of log4j
- * \ingroup XBT_API
- * \brief This section describes the API to the log functions used
- * everywhere in this project.
- */
- /** \defgroup XBT_sysdep All system dependency
- * \ingroup XBT_API
- * \brief This section describes many macros/functions that can serve as
- * an OS abstraction.
- */
+/** \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 */
+
+/** \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 API of SURF
- * \ingroup SimGrid_API
- */
+/** \defgroup SURF_API SURF (simulator kernel)
+ \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).
-/** \defgroup MSG_API API of MSG
- * \ingroup SimGrid_API
- */
- /** \defgroup m_datatypes_management MSG Data Types
- * \ingroup MSG_API
- * \brief This section describes the different datatypes provided by MSG.
- *
- */
+ Please note that as it is not really intended for public use,
+ this module is only partially documented.
+*/
- /** \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 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?).
- /** \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
- */
+ \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 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 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.
+
+ \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.
+
+ Code related: too long to be written here. See the TODO file
+
+ @{
+*/
- /** \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.
- */
+ /** \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 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.
- */
+/** @} */
- /** \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 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.
+
+ \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).
+
+ */
