Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Reorganizing and cleaning the doc
authoralegrand <alegrand@48e7efb5-ca39-0410-a469-dd3cf9ba447f>
Mon, 7 Feb 2005 06:19:56 +0000 (06:19 +0000)
committeralegrand <alegrand@48e7efb5-ca39-0410-a469-dd3cf9ba447f>
Mon, 7 Feb 2005 06:19:56 +0000 (06:19 +0000)
git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@890 48e7efb5-ca39-0410-a469-dd3cf9ba447f

18 files changed:
include/msg/datatypes.h
src/modules.doc
src/msg/environment.c
src/msg/global.c
src/msg/gos.c
src/msg/host.c
src/msg/m_process.c
src/msg/task.c
src/xbt/context.c
src/xbt/dict.c
src/xbt/dynar.c
src/xbt/error.c
src/xbt/fifo.c
src/xbt/heap.c
src/xbt/log.c
src/xbt/set.c
src/xbt/swag.c
src/xbt/sysdep.c

index d1ad6ec..0dc9911 100644 (file)
@@ -8,6 +8,10 @@
 #ifndef MSG_DATATYPE_H
 #define MSG_DATATYPE_H
 
 #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  
 /********************************* Host **************************************/
 
 /** @name Host datatype  
index c85f3dc..80d5e16 100644 (file)
-/** \defgroup SimGrid_API  API of SimGrid */
+/** 
+  \defgroup SimGrid_API  API of SimGrid */
 
 /** \defgroup XBT_API      XBT (eXtended Bundle of tools)
 
 /** \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.
-     
-<h3>Overview</h3>
+/**    \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.
-
-<h3>Category hierarchy</h3>
-
-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.
-
-<h3>Priority</h3>
-
-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 <i>warning</i>.
-
-<code>CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5,
-"oops");</code>
-
-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:
-
-<code>CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops");</code>
-
-<h3>Default category</h3>
-  
-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:
-
-<code>WARN3("Values are: %d and '%s'", 5, "oops");</code>
-
-Only one default category can be created per file, though multiple
-non-defaults can be created and used.
-
-<h3>Example</h3>
-
-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 &gt;= INFO. * /
-       CWARN2(VSS, "Low fuel level.");
-
-       / * This request is disabled, because DEBUG &lt; 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 &gt;= INFO.  * /
-       INFO1("Located nearest gas station.");
-
-       / * This request is disabled, because DEBUG &lt; INFO. * /
-       DEBUG1("Exiting gas station search"); 
-}
-\endverbatim
-
-<h3>Configuration</h3>
-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.
-
-<h3>Performance</h3>
-
-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
-    
-<h3>Appenders</h3>
-
-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.
-
-<h3>Misc and Caveats</h3>
-
-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 <tt>setjump/longjmp</tt>) 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)
 
 /** \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 (<arnaud.legrand@imag.fr>) 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 (<arnaud.legrand@imag.fr>) 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
 
 /** \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 <em>process</em> is at the heart of the
-     *  simulator. A process may be defined as a <em>code</em>, with
-     *  some <em>private data</em>, executing in a <em>location</em>.
-     *  \see m_process_t
-     */
-
-    /** \defgroup m_host_management    Management Functions of Hosts
-     *  \ingroup MSG_API
-     *  \brief This section describes the host structure of MSG
-     * (#m_host_t) and the functions for managing it.
-     *  
-     *  A <em>location</em> (or <em>host</em>) is any possible place where
-     *  a process may run. Thus it may be represented as a
-     *  <em>physical resource with computing capabilities</em>, some
-     *  <em>mailboxes</em> to enable running process to communicate with
-     *  remote ones, and some <em>private data</em> that can be only
-     *  accessed by local process.
-     *  \see m_host_t
-     */
-
-    /** \defgroup m_task_management    Management Functions of Tasks
-     *  \ingroup MSG_API
-     *  \brief This section describes the task structure of MSG
-     *  (#m_task_t) and the functions for managing it.
-     *
-     *  Since most scheduling algorithms rely on a concept of task
-     *  that can be either <em>computed</em> locally or
-     *  <em>transferred</em> on another processor, it seems to be the
-     *  right level of abstraction for our purposes. A <em>task</em>
-     *  may then be defined by a <em>computing amount</em>, a
-     *  <em>message size</em> and some <em>private data</em>.
-     */
-
-    /** \defgroup msg_gos_functions    MSG Operating System Functions
-     *  \ingroup MSG_API
-     *  \brief This section describes the functions that can be used
-     *  by an agent for handling some task.
-     */
-
-    /** \defgroup 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
 
 /** \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:
- *   - <b>Communication facilities</b>: Exchanging messages between peers
- *   - <b>Virtualization</b>: 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:
+     - <b>Communication facilities</b>: Exchanging messages between peers
+     - <b>Virtualization</b>: 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
 
 /** \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).
+  
  */
  */
index e3eb278..a0fed43 100644 (file)
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(environment, msg,
                                "Logging specific to MSG (environment)");
 
 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
 /********************************* MSG **************************************/
 
 /** \ingroup msg_easier_life
@@ -55,8 +61,8 @@ void MSG_create_environment(const char *file) {
   char *name = NULL;
   void *workstation = NULL;
 
   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);
 
   xbt_dict_foreach(workstation_set, cursor, name, workstation) {
     __MSG_host_create(name, workstation, NULL);
index 877d5f1..5db4445 100644 (file)
@@ -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); */
 
 /* 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
 /********************************* MSG **************************************/
 
 /** \ingroup msg_simulation
@@ -225,6 +231,17 @@ void MSG_set_verbosity(MSG_outputmode_t mode)
   CRITICAL0("MSG_set_verbosity : Not implemented yet.");
 }
 
   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.
  *
 /** \ingroup m_channel_management
  * \brief Set the number of channel in the simulation.
  *
index 2bb88bf..ba982f8 100644 (file)
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(gos, msg,
                                "Logging specific to MSG (gos)");
 
 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.
  */
 /** \ingroup msg_gos_functions
  * \brief This function is now deprecated and useless. Please stop using it.
  */
index d008e2b..c2d6a76 100644 (file)
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(host, msg,
                                "Logging specific to MSG (host)");
 
 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 <em>location</em> (or <em>host</em>) is any possible place where
+ *  a process may run. Thus it may be represented as a
+ *  <em>physical resource with computing capabilities</em>, some
+ *  <em>mailboxes</em> to enable running process to communicate with
+ *  remote ones, and some <em>private data</em> that can be only
+ *  accessed by local process.
+ *  \see m_host_t
+ */
+
 /********************************* Host **************************************/
 m_host_t __MSG_host_create(const char *name,
                         void *workstation,
 /********************************* Host **************************************/
 m_host_t __MSG_host_create(const char *name,
                         void *workstation,
index 50f83ef..50bd95c 100644 (file)
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(m_process, msg,
                                "Logging specific to MSG (process)");
 
 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 <em>process</em> is at the heart of the
+ *  simulator. A process may be defined as a <em>code</em>, with
+ *  some <em>private data</em>, executing in a <em>location</em>.
+ *  \see m_process_t
+ */
+
 /******************************** Process ************************************/
 /** \ingroup m_process_management
  * \brief Creates and runs a new #m_process_t.
 /******************************** Process ************************************/
 /** \ingroup m_process_management
  * \brief Creates and runs a new #m_process_t.
index 007160c..80a7c72 100644 (file)
@@ -13,6 +13,18 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(task, msg,
 
 static char sprint_buffer[64];
 
 
 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 <em>computed</em> locally or
+ *  <em>transferred</em> on another processor, it seems to be the
+ *  right level of abstraction for our purposes. A <em>task</em>
+ *  may then be defined by a <em>computing amount</em>, a
+ *  <em>message size</em> and some <em>private data</em>.
+ */
+
 /********************************* Task **************************************/
 /** \ingroup m_task_management
  * \brief Creates a new #m_task_t.
 /********************************* Task **************************************/
 /** \ingroup m_task_management
  * \brief Creates a new #m_task_t.
index bfaac45..6e367a0 100644 (file)
 #include "xbt/error.h"
 #include "xbt/dynar.h"
 #include "gras_config.h"
 #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 <tt>setjump/longjmp</tt>) to schedule non-preemptible 
+  *  threads.
+  */
+
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(context, xbt, "Context");
 
 /* #define WARNING(format, ...) (fprintf(stderr, "[%s , %s : %d] ", __FILE__, __FUNCTION__, __LINE__),\ */
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(context, xbt, "Context");
 
 /* #define WARNING(format, ...) (fprintf(stderr, "[%s , %s : %d] ", __FILE__, __FUNCTION__, __LINE__),\ */
index fb87393..d541f05 100644 (file)
 
 #include <stdio.h>
 
 
 #include <stdio.h>
 
+/** \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 ]#################################################*/
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dict,xbt,
    "Dictionaries provide the same functionnalities than hash tables");
 /*####[ Private prototypes ]#################################################*/
index 6b0bcd8..777f226 100644 (file)
 #include "xbt/dynar.h"
 #include <sys/types.h>
 
 #include "xbt/dynar.h"
 #include <sys/types.h>
 
+/** \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 {
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dynar,xbt,"Dynamic arrays");
 
 typedef struct xbt_dynar_s {
index de142cf..fccc88b 100644 (file)
@@ -9,6 +9,9 @@
    under the terms of the license (GNU LGPL) which comes with this package. */
 
 #include "xbt/error.h"
    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.
 
 /**
  * \brief Usefull to do nice error repporting messages.
index e0c4121..d596daa 100644 (file)
 
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(fifo,xbt,"FIFO");
 
 
 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
  */
 /** \name Functions 
  *  \ingroup XBT_fifo
  */
index 8de439f..2ff7891 100644 (file)
 #include "xbt/sysdep.h"
 #include "xbt/error.h"
 #include "heap_private.h"
 #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 
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(heap, xbt, "Heap");
 
 /** \name Functions 
index 23d0f2d..b532cb0 100644 (file)
 #include "xbt/dynar.h"
 
 
 #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.
+     
+<h3>Overview</h3>
+     
+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.
+
+<h3>Category hierarchy</h3>
+
+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.
+
+<h3>Priority</h3>
+
+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 <i>warning</i>.
+
+<code>CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5,
+"oops");</code>
+
+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:
+
+<code>CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops");</code>
+
+<h3>Default category</h3>
+  
+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:
+
+<code>WARN3("Values are: %d and '%s'", 5, "oops");</code>
+
+Only one default category can be created per file, though multiple
+non-defaults can be created and used.
+
+<h3>Example</h3>
+
+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 &gt;= INFO. * /
+       CWARN2(VSS, "Low fuel level.");
+
+       / * This request is disabled, because DEBUG &lt; 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 &gt;= INFO.  * /
+       INFO1("Located nearest gas station.");
+
+       / * This request is disabled, because DEBUG &lt; INFO. * /
+       DEBUG1("Exiting gas station search"); 
+}
+\endverbatim
+
+<h3>Configuration</h3>
+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.
+
+<h3>Performance</h3>
+
+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
+    
+<h3>Appenders</h3>
+
+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.
+
+<h3>Misc and Caveats</h3>
+
+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
 --------------------
 /*
 FAIRE DES ZOLIS LOGS
 --------------------
index 899fd82..39c1032 100644 (file)
 
 #include "xbt/set.h"
 
 
 #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 ]####################################################*/
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(set,xbt,"data container consisting in dict+dynar");
 
 /*####[ Type definition ]####################################################*/
index 5374dc1..2e3c732 100644 (file)
 #include "xbt/error.h"
 #include "xbt/swag.h"
 
 #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)
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(swag,xbt,"Swag : O(1) set library");
 
 #define PREV(obj,offset) xbt_swag_getPrev(obj,offset)
index 3426750..ecf11f6 100644 (file)
 
 #include <stdlib.h>
 
 
 #include <stdlib.h>
 
+/** \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");
 
 /****
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(sysdep, xbt, "System dependency");
 
 /****