From a9b94bc9be0c3ad5b5f816bf343152a3617a1bc2 Mon Sep 17 00:00:00 2001 From: alegrand Date: Mon, 7 Feb 2005 06:19:56 +0000 Subject: [PATCH] Reorganizing and cleaning the doc git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@890 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- include/msg/datatypes.h | 4 + src/modules.doc | 604 +++++++++++----------------------------- src/msg/environment.c | 10 +- src/msg/global.c | 17 ++ src/msg/gos.c | 5 + src/msg/host.c | 13 + src/msg/m_process.c | 11 + src/msg/task.c | 12 + src/xbt/context.c | 7 + src/xbt/dict.c | 6 + src/xbt/dynar.c | 5 + src/xbt/error.c | 3 + src/xbt/fifo.c | 6 + src/xbt/heap.c | 6 + src/xbt/log.c | 192 +++++++++++++ src/xbt/set.c | 4 + src/xbt/swag.c | 10 + src/xbt/sysdep.c | 5 + 18 files changed, 469 insertions(+), 451 deletions(-) diff --git a/include/msg/datatypes.h b/include/msg/datatypes.h index d1ad6eccee..0dc9911455 100644 --- a/include/msg/datatypes.h +++ b/include/msg/datatypes.h @@ -8,6 +8,10 @@ #ifndef MSG_DATATYPE_H #define MSG_DATATYPE_H +/** \defgroup m_datatypes_management MSG Data Types + \brief This section describes the different datatypes provided by MSG. +*/ + /********************************* Host **************************************/ /** @name Host datatype 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). + */ diff --git a/src/msg/environment.c b/src/msg/environment.c index e3eb278a2d..a0fed437db 100644 --- a/src/msg/environment.c +++ b/src/msg/environment.c @@ -11,6 +11,12 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(environment, msg, "Logging specific to MSG (environment)"); +/** \defgroup msg_easier_life Platform and Application management + * \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. + */ + /********************************* MSG **************************************/ /** \ingroup msg_easier_life @@ -55,8 +61,8 @@ void MSG_create_environment(const char *file) { char *name = NULL; void *workstation = NULL; - surf_workstation_resource_init_CLM03(file); -/* surf_workstation_resource_init_KCCFLN05(file); */ +/* surf_workstation_resource_init_CLM03(file); */ + surf_workstation_resource_init_KCCFLN05(file); xbt_dict_foreach(workstation_set, cursor, name, workstation) { __MSG_host_create(name, workstation, NULL); diff --git a/src/msg/global.c b/src/msg/global.c index 877d5f1d46..5db4445c1b 100644 --- a/src/msg/global.c +++ b/src/msg/global.c @@ -16,6 +16,12 @@ MSG_Global_t msg_global = NULL; /* static void MarkAsFailed(m_task_t t, TBX_HashTable_t failedProcessList); */ /* static xbt_fifo_t MSG_buildFailedHostList(long double a, long double b); */ +/** \defgroup msg_simulation MSG simulation Functions + * \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. + */ + /********************************* MSG **************************************/ /** \ingroup msg_simulation @@ -225,6 +231,17 @@ void MSG_set_verbosity(MSG_outputmode_t mode) CRITICAL0("MSG_set_verbosity : Not implemented yet."); } +/** \defgroup m_channel_management Understanding channels + * \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 m_channel_management * \brief Set the number of channel in the simulation. * diff --git a/src/msg/gos.c b/src/msg/gos.c index 2bb88bf9af..ba982f87d8 100644 --- a/src/msg/gos.c +++ b/src/msg/gos.c @@ -11,6 +11,11 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(gos, msg, "Logging specific to MSG (gos)"); +/** \defgroup msg_gos_functions MSG Operating System Functions + * \brief This section describes the functions that can be used + * by an agent for handling some task. + */ + /** \ingroup msg_gos_functions * \brief This function is now deprecated and useless. Please stop using it. */ diff --git a/src/msg/host.c b/src/msg/host.c index d008e2b465..c2d6a76acf 100644 --- a/src/msg/host.c +++ b/src/msg/host.c @@ -11,6 +11,19 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(host, msg, "Logging specific to MSG (host)"); +/** \defgroup m_host_management Management functions of Hosts + * \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 + */ + /********************************* Host **************************************/ m_host_t __MSG_host_create(const char *name, void *workstation, diff --git a/src/msg/m_process.c b/src/msg/m_process.c index 50f83ef122..50bd95c025 100644 --- a/src/msg/m_process.c +++ b/src/msg/m_process.c @@ -11,6 +11,17 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(m_process, msg, "Logging specific to MSG (process)"); +/** \defgroup m_process_management Management Functions of Agents + * \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 + */ + /******************************** Process ************************************/ /** \ingroup m_process_management * \brief Creates and runs a new #m_process_t. diff --git a/src/msg/task.c b/src/msg/task.c index 007160c03a..80a7c72692 100644 --- a/src/msg/task.c +++ b/src/msg/task.c @@ -13,6 +13,18 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(task, msg, static char sprint_buffer[64]; +/** \defgroup m_task_management Managing functions of Tasks + * \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. + */ + /********************************* Task **************************************/ /** \ingroup m_task_management * \brief Creates a new #m_task_t. diff --git a/src/xbt/context.c b/src/xbt/context.c index bfaac45266..6e367a0560 100644 --- a/src/xbt/context.c +++ b/src/xbt/context.c @@ -14,6 +14,13 @@ #include "xbt/error.h" #include "xbt/dynar.h" #include "gras_config.h" + + /** \defgroup XBT_context User-level context library + * \brief This section describes how to use high-level functions + * (as opposed to setjump/longjmp) to schedule non-preemptible + * threads. + */ + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(context, xbt, "Context"); /* #define WARNING(format, ...) (fprintf(stderr, "[%s , %s : %d] ", __FILE__, __FUNCTION__, __LINE__),\ */ diff --git a/src/xbt/dict.c b/src/xbt/dict.c index fb87393c85..d541f051fd 100644 --- a/src/xbt/dict.c +++ b/src/xbt/dict.c @@ -14,6 +14,12 @@ #include +/** \defgroup XBT_dict A generic dictionnary + * \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. + */ + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dict,xbt, "Dictionaries provide the same functionnalities than hash tables"); /*####[ Private prototypes ]#################################################*/ diff --git a/src/xbt/dynar.c b/src/xbt/dynar.c index 6b0bcd884a..777f226a86 100644 --- a/src/xbt/dynar.c +++ b/src/xbt/dynar.c @@ -14,6 +14,11 @@ #include "xbt/dynar.h" #include +/** \defgroup XBT_dynar A generic dynamic array + * \brief This section describes the API to generic dynamic array (vector). + */ + + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dynar,xbt,"Dynamic arrays"); typedef struct xbt_dynar_s { diff --git a/src/xbt/error.c b/src/xbt/error.c index de142cfe1c..fccc88b5ea 100644 --- a/src/xbt/error.c +++ b/src/xbt/error.c @@ -9,6 +9,9 @@ under the terms of the license (GNU LGPL) which comes with this package. */ #include "xbt/error.h" +/** \defgroup XBT_error Error tracking support. + * \brief This section describes a set of macros used to handle errors easily. + */ /** * \brief Usefull to do nice error repporting messages. diff --git a/src/xbt/fifo.c b/src/xbt/fifo.c index e0c41218d5..d596daa462 100644 --- a/src/xbt/fifo.c +++ b/src/xbt/fifo.c @@ -11,6 +11,12 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(fifo,xbt,"FIFO"); +/** \defgroup XBT_fifo A generic workqueue + * \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. + */ + /** \name Functions * \ingroup XBT_fifo */ diff --git a/src/xbt/heap.c b/src/xbt/heap.c index 8de439f5d5..2ff78913c5 100644 --- a/src/xbt/heap.c +++ b/src/xbt/heap.c @@ -10,6 +10,12 @@ #include "xbt/sysdep.h" #include "xbt/error.h" #include "heap_private.h" + + +/** \defgroup XBT_heap A generic heap data structure + * \brief This section describes the API to generic heap with O(log(n)) access. + */ + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(heap, xbt, "Heap"); /** \name Functions diff --git a/src/xbt/log.c b/src/xbt/log.c index 23d0f2d474..b532cb0260 100644 --- a/src/xbt/log.c +++ b/src/xbt/log.c @@ -19,6 +19,198 @@ #include "xbt/dynar.h" +/** \defgroup XBT_log Logging support. + * \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. + +*/ + /* FAIRE DES ZOLIS LOGS -------------------- diff --git a/src/xbt/set.c b/src/xbt/set.c index 899fd827d4..39c1032111 100644 --- a/src/xbt/set.c +++ b/src/xbt/set.c @@ -16,6 +16,10 @@ #include "xbt/set.h" +/** \defgroup XBT_set A generic set datatype + * \brief A data container consisting in \ref XBT_dict and \ref XBT_dynar + */ + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(set,xbt,"data container consisting in dict+dynar"); /*####[ Type definition ]####################################################*/ diff --git a/src/xbt/swag.c b/src/xbt/swag.c index 5374dc118d..2e3c7325ab 100644 --- a/src/xbt/swag.c +++ b/src/xbt/swag.c @@ -15,6 +15,16 @@ #include "xbt/error.h" #include "xbt/swag.h" +/** \defgroup XBT_swag A specific set datatype + * \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. + */ + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(swag,xbt,"Swag : O(1) set library"); #define PREV(obj,offset) xbt_swag_getPrev(obj,offset) diff --git a/src/xbt/sysdep.c b/src/xbt/sysdep.c index 34267507a6..ecf11f6681 100644 --- a/src/xbt/sysdep.c +++ b/src/xbt/sysdep.c @@ -15,6 +15,11 @@ #include +/** \defgroup XBT_sysdep All system dependency + * \brief This section describes many macros/functions that can serve as + * an OS abstraction. + */ + XBT_LOG_NEW_DEFAULT_SUBCATEGORY(sysdep, xbt, "System dependency"); /**** -- 2.20.1