X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/e6692e68ddfe1ef3234cacab53edb44277ae4405..1d788f0aa070c370acfaa33dee4004958c48c145:/src/modules.doc diff --git a/src/modules.doc b/src/modules.doc index fafe88603a..30ad7c537a 100644 --- a/src/modules.doc +++ b/src/modules.doc @@ -1,154 +1,192 @@ -/** \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 setjump/longjmp) 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_set A generic set datatype - * \ingroup XBT_API - * \brief A data container consisting in \ref XBT_dict and \ref XBT_dynar - */ - /** \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 - * \brief (Not documented yet). - * +/** \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 () and we'll see if - * it is feasible or not (hopefully it should be but who knows). - */ + 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. -/** \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. - * - */ + It is where platform models are encoded. If you need a model that is not + encoded yet, please tell me () and we'll + see if it is feasible or not (hopefully it should be but who knows). - /** \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 process is at the heart of the - * simulator. A process may be defined as a code, with - * some private data, executing in a location. - * \see m_process_t - */ + Please note that as it is not really intended for public use, + this module is only partially documented. +*/ - /** \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 location (or host) is any possible place where - * a process may run. Thus it may be represented as a - * physical resource with computing capabilities, some - * mailboxes to enable running process to communicate with - * remote ones, and some private data that can be only - * accessed by local process. - * \see m_host_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?). + + \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 computed locally or - * transferred on another processor, it seems to be the - * right level of abstraction for our purposes. A task - * may then be defined by a computing amount, a - * message size and some private data. - */ - /** \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 + - Communication facilities: 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. + - Virtualization: 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). + + */