From: mquinson Date: Sun, 6 Feb 2005 21:17:20 +0000 (+0000) Subject: Little reorganization of XBT, huge adding of log documentation, placeholder for the... X-Git-Tag: v3.3~4462 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/7392b17f0fee990af059ca94a2141236aa24d0c1 Little reorganization of XBT, huge adding of log documentation, placeholder for the several progenv git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@889 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- diff --git a/src/modules.doc b/src/modules.doc index fafe88603a..c85f3dc886 100644 --- a/src/modules.doc +++ b/src/modules.doc @@ -1,65 +1,269 @@ /** \defgroup SimGrid_API API of SimGrid */ -/** \defgroup XBT_API API of the toolbox (FIFO, hashtables, macros...) +/** \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_ground Grounding features of the XBT (logging and error reporting) + \ingroup XBT_API +*/ + /** \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

+ +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_API + * \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_API + * \ingroup XBT_structs * \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 + * \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_API + * \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_API - * \brief Warning, this module is done to be efficient and performs tons of + * \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_API - * \brief This section describes the API to generic heap. + * \ingroup XBT_structs + * \brief This section describes the API to generic heap with O(log(n)) access. */ - /** \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_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_API + * \ingroup XBT_port * \brief This section describes many macros/functions that can serve as * an OS abstraction. */ -/** \defgroup SURF_API API of SURF +/** \defgroup SURF_API SURF (simulator kernel) * \ingroup SimGrid_API - * \brief (Not documented yet). + * \brief Kernel of all the simulators used in SimGrid, and associated models. * * SURF provides the core functionnalities to simulate a virtual @@ -72,10 +276,27 @@ * 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 API of MSG +/** \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 @@ -152,3 +373,93 @@ * 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. + */ + + /** \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). + */ + + +/** \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). + * + */