X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/7392b17f0fee990af059ca94a2141236aa24d0c1..a9b94bc9be0c3ad5b5f816bf343152a3617a1bc2:/src/modules.doc diff --git a/src/modules.doc b/src/modules.doc index c85f3dc886..80d5e16a01 100644 --- a/src/modules.doc +++ b/src/modules.doc @@ -1,465 +1,171 @@ -/** \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. - -

Overview

+/** \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. - -

Category hierarchy

- -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. - -

Priority

- -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 warning. - -CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5, -"oops"); - -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: - -CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops"); - -

Default category

- -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: - -WARN3("Values are: %d and '%s'", 5, "oops"); - -Only one default category can be created per file, though multiple -non-defaults can be created and used. - -

Example

- -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 - -

Configuration

-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. - -

Performance

- -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 - -

Appenders

- -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. - -

Misc and Caveats

- -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 setjump/longjmp) 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 () 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 () 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 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 - */ - - /** \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 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 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 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. - */ + \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). +*/ +/** \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: - * - Communication facilities: Exchanging messages between peers - * - Virtualization: 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. + + 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: + - Communication facilities: Exchanging messages between peers + - Virtualization: Running both on top of the simulator and on + top of real platforms, and portability support. +*/ +/** \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). - /** \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. - */ - - /** \defgroup GRAS_virtu Syscalls - * \ingroup GRAS_API - * \brief System call abstraction layer (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. */ + +/** \defgroup GRAS_virtu Syscalls + \ingroup GRAS_API + \brief System call abstraction layer (Virtualization). */ /** \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. + + 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). + */