DataDescriptor API
+<!-- ##### SECTION ./tmpl/Dynamic_arrays.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/Dynamic_arrays.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/Dynamic_arrays.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/Dynamic_arrays.sgml:Title ##### -->
+Dynamic arrays
+
+
<!-- ##### SECTION ./tmpl/ErrLog.sgml:Long_Description ##### -->
<para>
config
-<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Title ##### -->
+Data description callbacks persistant state
+
+
+<!-- ##### SECTION ./tmpl/dd_internal.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dd_internal.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dd_internal.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/dd_internal.sgml:Title ##### -->
+Implementation of data description
+
+
+<!-- ##### SECTION ./tmpl/dico.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dico.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dico.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/dico.sgml:Title ##### -->
+dico
+
+
+<!-- ##### SECTION ./tmpl/dynar.sgml:Long_Description ##### -->
+<para>
+This module provide the quite usual dynamic array facility.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dynar.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/dynar.sgml:Short_Description ##### -->
+Dynamic array
+
+
+<!-- ##### SECTION ./tmpl/dynar.sgml:Title ##### -->
+dynar
+
+
+<!-- ##### SECTION ./tmpl/gras-overview.sgml:Long_Description ##### -->
+ <para>This document introduce the GRAS library (<emphasis>Grid Reality
+ And Simulation</emphasis>, or according to my english dictionary,
+ <emphasis>Generally Recognized As Safe</emphasis> ;).</para>
+
+ <refsect2>
+ <title>Overview</title>
+ <para>The purpose of the GRAS is to allow the developpement of
+ distributed programs which will work with as few as possible
+ modification both on the SimGrid simulator (SG), and in the Real Life
+ (RL).</para>
+
+ <para>Here are the problems when you want to do so:
+ <itemizedlist>
+ <listitem>
+ <para>Communication in SG is done by passing tasks, while in
+ RL, you have to deal with sockets (or any wrapper to it).</para>
+ </listitem>
+ <listitem><para>In RL, each process should provide a main()
+ function, and it's obviously not the case in SG.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </refsect2>
+ <refsect2>
+ <title>Application class target</title>
+ <para>If you want to run your code both in RL and in SG, you won't be
+ able to use the full set of features offered by any of those two
+ worlds. GRAS tries to provide a suffisent set of features to develop
+ your application, and implement them in both worlds.</para>
+
+ <para>GRAS uses the paradigm of <emphasis>event-driven
+ programming</emphasis>, which is an extension to the message-passing
+ one. Any process of a typical event-driven application declares
+ callback to incoming events, which can be messages from other
+ processes, timers or others.</para>
+
+ <para>All messages have an header, specifying its type, and attached
+ data, represented as one or several C structures. In order to send
+ the data over the network in RL, a type-description mecanism is
+ provided, and the RL version of GRAS implements CDR
+ functionnalities. That is to say that the data are sent in the native
+ format of the sender host, and converted on the destination host only
+ if needed.</para>
+
+ <para>In order to not reimplement the wheel, GRAS use existing code,
+ and adapt them to make them work together. The SG version naturally
+ use the SimGrid toolkit, while the RL version is based over the
+ communication library used in NWS (note that this library was somehow
+ modified, since the previous version use XDR, ie both the sender and
+ the receiver convert the data from/to a so called network
+ format). That's why some basic knowledge about how NWS work is
+ supposed in this document. But don't worry, you only have to know the
+ basics about NWS, the internals needed to understand the document
+ will be presented when needed.</para>
+ </refsect2>
+
+
+<!-- ##### SECTION ./tmpl/gras-overview.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-overview.sgml:Short_Description ##### -->
+Overview of the GRAS library
+
+
+<!-- ##### SECTION ./tmpl/gras-overview.sgml:Title ##### -->
+Overview
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml.sgml:Title ##### -->
+./gras-sections.txt.sgml
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras-sections.txt.sgml:Title ##### -->
+./gras-sections.txt
+
+
+<!-- ##### SECTION ./tmpl/gras.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras.sgml:Title ##### -->
+gras
+
+
+<!-- ##### SECTION ./tmpl/gras_private.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras_private.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras_private.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/gras_private.sgml:Title ##### -->
+gras_private
+
+
+<!-- ##### SECTION ./tmpl/gras_rl.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras_rl.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras_rl.sgml:Short_Description ##### -->
+Implementation of GRAS suited for real life.
+
+
+<!-- ##### SECTION ./tmpl/gras_rl.sgml:Title ##### -->
+RL
+
+
+<!-- ##### SECTION ./tmpl/gras_sg.sgml:Long_Description ##### -->
+<para>
+ SimGrid was designed to ease the comparison of algorithms and
+ heuristics. That way, a lot of complicated notion from the system layer
+ were volontary left off. For example, migrating a process from an host to
+ another is as easy as: MSG_process_change_host(process, new_host).
+</para>
+
+<para>
+ No need to tell that performing this operation on real platform is really
+ harder. This simplification is a very good thing when you want to rapidly
+ prototype code, but makes things somehow more complicated in GRAS since
+ we want to have a realistic API, since it have to be implemented in
+ reality also.
+</para>
+
+<para>
+ The best example of complexity in GRAS_SG induced by simplicity in
+ SimGrid is the sockets handling. There is no "socket" in SG, but only
+ m_channel_t. In contrary to sockets from RL, no special treatment is
+ needed for a process before writing or reading on/from a channel. So, a
+ given channel can be pooled by more than one process. Likewise, you can
+ send data to a channel that nobody is actually listening to.
+</para>
+
+<para>
+ The SG implementation of GRAS repport as an error the fact that nobody is
+ listening to the socket when trying to open a socket, or send stuff using
+ a previously openned socket. That way, the SG version can be used to
+ debug all syncronization issues. For that, we store mainly the PID of
+ both the sender and the receiver in the socket structure, and then
+ resolve PID->process at the lastest moment. This search is a bit
+ expensive, but as long as there is no real garbage collection in SG, with
+ the information "dead process" within the structure, it's the only
+ solution to make sure that we won't dereference pointers to an old freed
+ structure when the process on the other side of the structure did finish
+ since the creation of the socket.
+</para>
+
+<para>
+ As said in the overview, the processes can declare to hear on several
+ sockets, but all incoming messages are handled by the same loop. So, we
+ can use only one channel per process, and use a table on each host to
+ determine to which process a message should be delivered depending on the
+ socket number provided by the sender.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/gras_sg.sgml:See_Also ##### -->
+<para>
+RL, the implementation suited for real life.
+</para>
+
+<!--
+Local variables:
+sgml-parent-document:\.\./gras-docs\.sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
+
+
+<!-- ##### SECTION ./tmpl/gras_sg.sgml:Short_Description ##### -->
+Implementation of GRAS on top of the simulator.
+
+
+<!-- ##### SECTION ./tmpl/gras_sg.sgml:Title ##### -->
+SG
+
+
+<!-- ##### SECTION ./tmpl/nws_comm.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/nws_comm.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/nws_comm.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/nws_comm.sgml:Title ##### -->
+nws_comm
+
+
+<!-- ##### SECTION ./tmpl/tbx_cfg.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_cfg.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_cfg.sgml:Short_Description ##### -->
+Configuration facilities.
+
+
+<!-- ##### SECTION ./tmpl/tbx_cfg.sgml:Title ##### -->
+Config
+
+
+<!-- ##### SECTION ./tmpl/tbx_dico.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_dico.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_dico.sgml:Short_Description ##### -->
+Data container associating data to a string key.
+
+
+<!-- ##### SECTION ./tmpl/tbx_dico.sgml:Title ##### -->
+Dictionnary
+
+
+<!-- ##### SECTION ./tmpl/tbx_dynar.sgml:Long_Description ##### -->
+<para>
+This module provide the quite usual dynamic array facility.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_dynar.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_dynar.sgml:Short_Description ##### -->
+Use arrays, forget about malloc
+
+
+<!-- ##### SECTION ./tmpl/tbx_dynar.sgml:Title ##### -->
+Dynamic array
+
+
+<!-- ##### SECTION ./tmpl/tbx_err.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_err.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_err.sgml:Short_Description ##### -->
+Error reporting
+
+
+<!-- ##### SECTION ./tmpl/tbx_err.sgml:Title ##### -->
+Errors handling
+
+
+<!-- ##### SECTION ./tmpl/tbx_log.sgml:Long_Description ##### -->
+<para>
+ 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.
+</para>
+
+<refsect2>
+ <title>Overview</title>
+
+ <para>
+ 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.
+ </para>
+</refsect2>
+
+<refsect2>
+ <title>Category hierarchy</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>@GRAS_LOG_NEW_CATEGORY(MyCat);</para>
+ <para>create a new root</para>
+ </listitem>
+
+ <listitem>
+ <para>@GRAS_LOG_NEW_SUBCATEGORY(MyCat, ParentCat);</para>
+ <para>Create a new category being child of the category ParentCat</para>
+ </listitem>
+
+ <listitem>
+ <para>@GRAS_LOG_NEW_DEFAULT_CATEGORY(MyCat);</para>
+ <para>Like GRAS_LOG_NEW_CATEGORY, but the new category is the default one
+ in this file</para>
+ </listitem>
+
+ <listitem>
+ <para>@GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, ParentCat);</para>
+ <para>Like GRAS_LOG_NEW_SUBCATEGORY, but the new category is the default one
+ in this file</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The parent cat can be defined in the same file or in another file, but each
+ category may have only one definition.
+ </para>
+
+ <para>
+ Typically, there will be a Category for each module and sub-module, so you
+ can independently control logging for each module.
+ </para>
+</refsect2>
+
+<refsect2>
+ <title>Priority</title>
+
+ <para>
+ A category may be assigned a threshold priorty. The set of priorites are
+ defined by the @gras_log_priority_t enum. Their values are DEBUG, VERBOSE,
+ INFO, WARNING, ERROR and CRITICAL.
+ </para>
+
+ <para>
+ If a given category is not assigned a threshold priority, then it inherits
+ one from its closest ancestor with an assigned threshold.
+ </para>
+
+ <para>
+ To ensure that all categories can eventually inherit a threshold, the root
+ category always has an assigned threshold priority.
+ </para>
+
+ <para>
+ 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.
+ 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.
+ </para>
+
+ <para>
+ Here is an example of the most basic type of macro:
+ </para>
+
+ <programlisting>CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5, "oops");</programlisting>
+
+ <para>This is a logging request with priority WARN.</para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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:
+ </para>
+
+ <programlisting>CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops");</programlisting>
+</refsect2>
+
+<refsect2>
+ <title>Default category</title>
+
+ <para>
+ If @GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, Parent) or
+ @GRAS_LOG_NEW_DEFAULT_CATEGORY(MyCat) is used to create the category, then
+ the even shorter form can be used:
+ </para>
+
+ <programlisting>WARN3("Values are: %d and '%s'", 5, "oops");</programlisting>
+
+ <para>
+ Only one default category can be created per file, though multiple
+ non-defaults can be created and used.
+ </para>
+</refsect2>
+
+<refsect2>
+ <title>Example</title>
+
+ <para>Here is a more complete example:</para>
+
+ <programlisting>
+ #include "gras.h"
+
+ /* create a category and a default subcategory */
+ GRAS_LOG_NEW_CATEGORY(VSS);
+ GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(SA, VSS);
+
+ main() {
+ /* Now set the parent's priority.
+ (the string would typcially be a runtime option) */
+ gras_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");
+ }</programlisting>
+</refsect2>
+
+<refsect2>
+ <title>Configuration</title>
+
+ <para>
+ Configuration is typically done during program initialization by invoking
+ the gras_log_control_set() method. The control string passed to it
+ typically comes from the command line. Look at the doucmentation for that
+ function for the format of the control string.
+ </para>
+</refsect2>
+
+<refsect2>
+ <title>Performance</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ There is also compile time constant, @GRAS_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 typically be compiled with
+ "-DGRAS_LOG_STATIC_THRESHOLD=gras_log_priority_infinite".
+ </para>
+</refsect2>
+
+<refsect2>
+ <title>Appenders</title>
+
+ <para>
+ Each category has an optional appender. An appender is a pointer to a
+ structure whcih starts with a pointer to a doAppend() function. DoAppend()
+ prints a message to a log.
+ </para>
+
+ <para>
+ WHen a category is passed a message by one of the logging macros, the
+ category performs the following actions:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ if the category has an appender, the message is passed to the
+ appender's doAppend() function,
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ if 'willLogToParent' is true for the category, the message is passed
+ to the category's parent.
+ </para>
+
+ <para>
+ By default, all categories except root have no appender and
+ 'willLogToParent' is true. This situation causes all messages to be
+ logged by the root category's appender.
+ </para>
+
+ <para>
+ Typically, you would only change the root category's appender when you
+ wanted, say, a different output format. Copying defaultLogAppender.c
+ would be a good start.
+ </para>
+
+ <para>
+ The default appender function currently prints to stderr, but more
+ would be needed, like the one able to send the logs to a remote
+ dedicated server.
+ </para>
+ </listitem>
+ </itemizedlist>
+</refsect2>
+
+<refsect2>
+ <title>Misc and Caveats</title>
+
+ <para>
+ Do not use any of the macros that start with '_'.
+ </para>
+
+ <para>
+ The current set of macros force each file to use categories declared in
+ that file. This is intentional. Make the category a child of the file's
+ module category.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ Careful, category names are global variables.
+ </para>
+</refsect2>
+
+
+<!-- ##### SECTION ./tmpl/tbx_log.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_log.sgml:Short_Description ##### -->
+An easy-to-use, fast and flexible message logging architecture.
+
+
+<!-- ##### SECTION ./tmpl/tbx_log.sgml:Title ##### -->
+Logging facilities
+
+
+<!-- ##### SECTION ./tmpl/tbx_set.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_set.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/tbx_set.sgml:Short_Description ##### -->
+Data storage for very quick retrieve
+
+
+<!-- ##### SECTION ./tmpl/tbx_set.sgml:Title ##### -->
+Data set
+
+
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/trp_socks.sgml:Title ##### -->
+Sockets
+
+
+<!-- ##### SECTION ./tmpl/xbt_cfg.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/dd_cbps.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_cfg.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_cfg.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/dd_cbps.sgml:Title ##### -->
-Data description callbacks persistant state
+<!-- ##### SECTION ./tmpl/xbt_cfg.sgml:Title ##### -->
+xbt_cfg
-<!-- ##### SECTION ./tmpl/dd_internal.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_dico.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/dd_internal.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_dico.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/dd_internal.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_dico.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/dd_internal.sgml:Title ##### -->
-Implementation of data description
+<!-- ##### SECTION ./tmpl/xbt_dico.sgml:Title ##### -->
+xbt_dico
-<!-- ##### SECTION ./tmpl/dico.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_err.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/dico.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_err.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/dico.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_err.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/dico.sgml:Title ##### -->
-dico
+<!-- ##### SECTION ./tmpl/xbt_err.sgml:Title ##### -->
+Errors
-<!-- ##### SECTION ./tmpl/dynar.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
<para>
-This module provide the quite usual dynamic array facility.
+
</para>
-<!-- ##### SECTION ./tmpl/dynar.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/dynar.sgml:Short_Description ##### -->
-Dynamic array
-
-
-<!-- ##### SECTION ./tmpl/dynar.sgml:Title ##### -->
-dynar
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/gras-overview.sgml:Long_Description ##### -->
- <para>This document introduce the GRAS library (<emphasis>Grid Reality
- And Simulation</emphasis>, or according to my english dictionary,
- <emphasis>Generally Recognized As Safe</emphasis> ;).</para>
-
- <refsect2>
- <title>Overview</title>
- <para>The purpose of the GRAS is to allow the developpement of
- distributed programs which will work with as few as possible
- modification both on the SimGrid simulator (SG), and in the Real Life
- (RL).</para>
- <para>Here are the problems when you want to do so:
- <itemizedlist>
- <listitem>
- <para>Communication in SG is done by passing tasks, while in
- RL, you have to deal with sockets (or any wrapper to it).</para>
- </listitem>
- <listitem><para>In RL, each process should provide a main()
- function, and it's obviously not the case in SG.</para>
- </listitem>
- </itemizedlist>
- </para>
- </refsect2>
- <refsect2>
- <title>Application class target</title>
- <para>If you want to run your code both in RL and in SG, you won't be
- able to use the full set of features offered by any of those two
- worlds. GRAS tries to provide a suffisent set of features to develop
- your application, and implement them in both worlds.</para>
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml
- <para>GRAS uses the paradigm of <emphasis>event-driven
- programming</emphasis>, which is an extension to the message-passing
- one. Any process of a typical event-driven application declares
- callback to incoming events, which can be messages from other
- processes, timers or others.</para>
- <para>All messages have an header, specifying its type, and attached
- data, represented as one or several C structures. In order to send
- the data over the network in RL, a type-description mecanism is
- provided, and the RL version of GRAS implements CDR
- functionnalities. That is to say that the data are sent in the native
- format of the sender host, and converted on the destination host only
- if needed.</para>
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
+<para>
- <para>In order to not reimplement the wheel, GRAS use existing code,
- and adapt them to make them work together. The SG version naturally
- use the SimGrid toolkit, while the RL version is based over the
- communication library used in NWS (note that this library was somehow
- modified, since the previous version use XDR, ie both the sender and
- the receiver convert the data from/to a so called network
- format). That's why some basic knowledge about how NWS work is
- supposed in this document. But don't worry, you only have to know the
- basics about NWS, the internals needed to understand the document
- will be presented when needed.</para>
- </refsect2>
+</para>
-<!-- ##### SECTION ./tmpl/gras-overview.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gras-overview.sgml:Short_Description ##### -->
-Overview of the GRAS library
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/gras-overview.sgml:Title ##### -->
-Overview
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml
-<!-- ##### SECTION ./tmpl/gras.sgml:Long_Description ##### -->
+
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gras.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gras.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/gras.sgml:Title ##### -->
-gras
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml
-<!-- ##### SECTION ./tmpl/gras_private.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gras_private.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gras_private.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/gras_private.sgml:Title ##### -->
-gras_private
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+xbt_swag.sgml.sgml.sgml.sgml.sgml
-<!-- ##### SECTION ./tmpl/gras_rl.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gras_rl.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/gras_rl.sgml:Short_Description ##### -->
-Implementation of GRAS suited for real life.
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/gras_rl.sgml:Title ##### -->
-RL
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml.sgml:Title ##### -->
+xbt_swag.sgml.sgml.sgml.sgml
-<!-- ##### SECTION ./tmpl/gras_sg.sgml:Long_Description ##### -->
-<para>
- SimGrid was designed to ease the comparison of algorithms and
- heuristics. That way, a lot of complicated notion from the system layer
- were volontary left off. For example, migrating a process from an host to
- another is as easy as: MSG_process_change_host(process, new_host).
-</para>
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml:Long_Description ##### -->
<para>
- No need to tell that performing this operation on real platform is really
- harder. This simplification is a very good thing when you want to rapidly
- prototype code, but makes things somehow more complicated in GRAS since
- we want to have a realistic API, since it have to be implemented in
- reality also.
-</para>
-<para>
- The best example of complexity in GRAS_SG induced by simplicity in
- SimGrid is the sockets handling. There is no "socket" in SG, but only
- m_channel_t. In contrary to sockets from RL, no special treatment is
- needed for a process before writing or reading on/from a channel. So, a
- given channel can be pooled by more than one process. Likewise, you can
- send data to a channel that nobody is actually listening to.
</para>
-<para>
- The SG implementation of GRAS repport as an error the fact that nobody is
- listening to the socket when trying to open a socket, or send stuff using
- a previously openned socket. That way, the SG version can be used to
- debug all syncronization issues. For that, we store mainly the PID of
- both the sender and the receiver in the socket structure, and then
- resolve PID->process at the lastest moment. This search is a bit
- expensive, but as long as there is no real garbage collection in SG, with
- the information "dead process" within the structure, it's the only
- solution to make sure that we won't dereference pointers to an old freed
- structure when the process on the other side of the structure did finish
- since the creation of the socket.
-</para>
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml:See_Also ##### -->
<para>
- As said in the overview, the processes can declare to hear on several
- sockets, but all incoming messages are handled by the same loop. So, we
- can use only one channel per process, and use a table on each host to
- determine to which process a message should be delivered depending on the
- socket number provided by the sender.
-</para>
-
-<!-- ##### SECTION ./tmpl/gras_sg.sgml:See_Also ##### -->
-<para>
-RL, the implementation suited for real life.
</para>
-<!--
-Local variables:
-sgml-parent-document:\.\./gras-docs\.sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-namecase-general:t
-sgml-general-insert-case:lower
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:2
-sgml-indent-data:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/gras_sg.sgml:Short_Description ##### -->
-Implementation of GRAS on top of the simulator.
-<!-- ##### SECTION ./tmpl/gras_sg.sgml:Title ##### -->
-SG
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml.sgml:Title ##### -->
+xbt_swag.sgml.sgml.sgml
-<!-- ##### SECTION ./tmpl/nws_comm.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/nws_comm.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/nws_comm.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/nws_comm.sgml:Title ##### -->
-nws_comm
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml.sgml:Title ##### -->
+xbt_swag.sgml.sgml
-<!-- ##### SECTION ./tmpl/trp_socks.sgml:Long_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml:Long_Description ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/trp_socks.sgml:See_Also ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml:See_Also ##### -->
<para>
</para>
-<!-- ##### SECTION ./tmpl/trp_socks.sgml:Short_Description ##### -->
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml:Short_Description ##### -->
-<!-- ##### SECTION ./tmpl/trp_socks.sgml:Title ##### -->
-Sockets
+<!-- ##### SECTION ./tmpl/xbt_swag.sgml.sgml:Title ##### -->
+xbt_swag.sgml
<!-- ##### MACRO BEGIN_DECL ##### -->
@a4:
@a5:
-<!-- ##### MACRO CCRITICAL6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### MACRO CDEBUG0 ##### -->
<para>
@a4:
@a5:
-<!-- ##### MACRO CDEBUG6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### MACRO CERROR0 ##### -->
<para>
@a4:
@a5:
-<!-- ##### MACRO CERROR6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### MACRO CINFO0 ##### -->
<para>
@a4:
@a5:
-<!-- ##### MACRO CINFO6 ##### -->
-<para>
-
-</para>
-
-@c:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### MACRO CLOG0 ##### -->
<para>
@a4:
@a5:
-<!-- ##### MACRO CLOG6 ##### -->
-<para>
-
-</para>
-
-@c:
-@p:
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
-<!-- ##### MACRO CRITICAL0 ##### -->
-<para>
-
-</para>
-
-@f:
-
-<!-- ##### MACRO CRITICAL1 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-
-<!-- ##### MACRO CRITICAL2 ##### -->
+<!-- ##### MACRO CLOG6 ##### -->
<para>
</para>
+@c:
+@p:
@f:
@a1:
@a2:
+@a3:
+@a4:
+@a5:
+@a6:
-<!-- ##### MACRO CRITICAL3 ##### -->
+<!-- ##### MACRO CRITICAL0 ##### -->
<para>
</para>
@f:
-@a1:
-@a2:
-@a3:
-<!-- ##### MACRO CRITICAL4 ##### -->
+<!-- ##### MACRO CRITICAL1 ##### -->
<para>
</para>
@f:
@a1:
-@a2:
-@a3:
-@a4:
-<!-- ##### MACRO CRITICAL5 ##### -->
+<!-- ##### MACRO CRITICAL2 ##### -->
<para>
</para>
@f:
@a1:
@a2:
-@a3:
-@a4:
-@a5:
-<!-- ##### MACRO CRITICAL6 ##### -->
+<!-- ##### MACRO CRITICAL3 ##### -->
<para>
</para>
@a1:
@a2:
@a3:
-@a4:
-@a5:
-@a6:
-<!-- ##### MACRO CVERB6 ##### -->
+<!-- ##### MACRO CRITICAL4 ##### -->
<para>
</para>
-@c:
@f:
@a1:
@a2:
@a3:
@a4:
-@a5:
-@a6:
-<!-- ##### MACRO CWARN6 ##### -->
+<!-- ##### MACRO CRITICAL5 ##### -->
<para>
</para>
-@c:
@f:
@a1:
@a2:
@a3:
@a4:
@a5:
-@a6:
<!-- ##### MACRO CWARNING6 ##### -->
<para>
@childToParent:
@Returns:
-<!-- ##### MACRO DEBUG6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### FUNCTION DROP_SOCKET ##### -->
<para>
</para>
-<!-- ##### MACRO ERROR6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### FUNCTION EstablishAnEar ##### -->
<para>
@HOST_FORMAT:
@NETWORK_FORMAT:
-<!-- ##### MACRO GRAS_DEFINE_TYPE ##### -->
-<para>
-
-</para>
-
-@name:
-@def:
-
<!-- ##### MACRO GRAS_LOG_DEFAULT_CATEGORY ##### -->
<para>
</para>
@catName:
+@desc:
<!-- ##### MACRO GRAS_LOG_NEW_DEFAULT_CATEGORY ##### -->
<para>
</para>
@cname:
+@desc:
<!-- ##### MACRO GRAS_LOG_NEW_DEFAULT_SUBCATEGORY ##### -->
<para>
@cname:
@parent:
+@desc:
<!-- ##### MACRO GRAS_LOG_NEW_SUBCATEGORY ##### -->
<para>
@catName:
@parent:
+@desc:
<!-- ##### MACRO GRAS_LOG_ROOT_CAT ##### -->
<para>
@format:
@Returns:
-<!-- ##### MACRO INFO6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### TYPEDEF IPAddress ##### -->
<para>
@sd:
@Returns:
-<!-- ##### MACRO VERB6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### MACRO VERSION ##### -->
<para>
</para>
-<!-- ##### MACRO WARN6 ##### -->
-<para>
-
-</para>
-
-@f:
-@a1:
-@a2:
-@a3:
-@a4:
-@a5:
-@a6:
-
<!-- ##### MACRO WARNING6 ##### -->
<para>
@ud:
-<!-- ##### FUNCTION gras_arch_selfid ##### -->
-<para>
-
-</para>
-
-@Returns:
-
-<!-- ##### FUNCTION gras_cb_register ##### -->
-<para>
-
-</para>
-
-@msgtype:
-@cb:
-@Returns:
-@message:
-@TTL:
-
-<!-- ##### USER_FUNCTION gras_cb_t ##### -->
-<para>
-
-</para>
-
-@expeditor:
-@payload:
-@Returns:
-@payload_type:
-@payload_data:
-@msg:
-
-<!-- ##### FUNCTION gras_cb_unregister ##### -->
-<para>
-
-</para>
-
-@msgtype:
-@cb:
-
-<!-- ##### FUNCTION gras_cbps_block_begin ##### -->
-<para>
-
-</para>
-
-@ps:
-
-<!-- ##### FUNCTION gras_cbps_block_end ##### -->
-<para>
-
-</para>
-
-@ps:
-
-<!-- ##### FUNCTION gras_cbps_i_pop ##### -->
-<para>
-
-</para>
-
-@ps:
-@Returns:
-
-<!-- ##### FUNCTION gras_cbps_i_push ##### -->
-<para>
-
-</para>
-
-@ps:
-@val:
-
-<!-- ##### FUNCTION gras_cbps_v_get ##### -->
-<para>
-
-</para>
-
-@ps:
-@name:
-@ddt:
-
-<!-- ##### FUNCTION gras_cbps_v_pop ##### -->
-<para>
-
-</para>
-
-@ps:
-@name:
-@ddt:
-@res:
-@Returns:
-
-<!-- ##### FUNCTION gras_cbps_v_push ##### -->
-<para>
-
-</para>
-
-@ps:
-@name:
-@data:
-@ddt:
-@Returns:
-
-<!-- ##### FUNCTION gras_cbps_v_set ##### -->
-<para>
-
-</para>
-
-@ps:
-@name:
-@data:
-@ddt:
-
<!-- ##### FUNCTION gras_cfg_check ##### -->
<para>
</para>
-@whereto:
@tocopy:
+@whereto:
@Returns:
<!-- ##### FUNCTION gras_cfg_dump ##### -->
</para>
-@whereto:
@Returns:
+@whereto:
<!-- ##### FUNCTION gras_cfg_register ##### -->
<para>
</para>
-@cfg:
-@name:
-@val:
-@Returns:
-
-<!-- ##### FUNCTION gras_cfg_set_parse ##### -->
-<para>
-
-</para>
-
-@cfg:
-@options:
-@Returns:
-
-<!-- ##### FUNCTION gras_cfg_set_string ##### -->
-<para>
-
-</para>
-
-@cfg:
-@name:
-@val:
-@Returns:
-
-<!-- ##### FUNCTION gras_cfg_set_vargs ##### -->
-<para>
-
-</para>
-
-@cfg:
-@pa:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_array_dyn ##### -->
-<para>
-
-</para>
-
-@name:
-@element_type:
-@dynamic_size:
-@dst:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_array_fixed ##### -->
-<para>
-
-</para>
-
-@name:
-@element_type:
-@fixed_size:
-@dst:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_by_name ##### -->
-<para>
-
-</para>
-
+@cfg:
@name:
+@val:
@Returns:
-@type:
-<!-- ##### MACRO gras_datadesc_by_symbol ##### -->
+<!-- ##### FUNCTION gras_cfg_set_parse ##### -->
<para>
</para>
-@name:
+@cfg:
+@options:
+@Returns:
-<!-- ##### FUNCTION gras_datadesc_cb_recv ##### -->
+<!-- ##### FUNCTION gras_cfg_set_string ##### -->
<para>
</para>
-@type:
-@post:
+@cfg:
+@name:
+@val:
+@Returns:
-<!-- ##### FUNCTION gras_datadesc_cb_send ##### -->
+<!-- ##### FUNCTION gras_cfg_set_vargs ##### -->
<para>
</para>
-@type:
-@pre:
+@cfg:
+@pa:
+@Returns:
<!-- ##### FUNCTION gras_datadesc_cb_set_post ##### -->
<para>
@code:
@def:
-<!-- ##### FUNCTION gras_datadesc_ref ##### -->
-<para>
-
-</para>
-
-@name:
-@referenced_type:
-@dst:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_ref_generic ##### -->
-<para>
-
-</para>
-
-@name:
-@selector:
-@dst:
-@Returns:
-@discriminant:
-
-<!-- ##### FUNCTION gras_datadesc_ref_pop_arr ##### -->
-<para>
-
-</para>
-
-@element_type:
-@dst:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_struct ##### -->
-<para>
-
-</para>
-
-@name:
-@dst:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_struct_append ##### -->
-<para>
-
-</para>
-
-@struct_type:
-@name:
-@field_type:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_struct_close ##### -->
-<para>
-
-</para>
-
-@struct_type:
-
-<!-- ##### USER_FUNCTION gras_datadesc_type_cb_int_t ##### -->
-<para>
-
-</para>
-
-@vars:
-@data:
-@Returns:
-@p_type:
-
-<!-- ##### USER_FUNCTION gras_datadesc_type_cb_void_t ##### -->
-<para>
-
-</para>
-
-@vars:
-@data:
-@p_type:
-
-<!-- ##### FUNCTION gras_datadesc_union ##### -->
-<para>
-
-</para>
-
-@name:
-@selector:
-@dst:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_union_append ##### -->
-<para>
-
-</para>
-
-@union_type:
-@name:
-@field_type:
-@Returns:
-
-<!-- ##### FUNCTION gras_datadesc_union_close ##### -->
-<para>
-
-</para>
-
-@union_type:
-
<!-- ##### FUNCTION gras_dd_cbps_block_begin ##### -->
<para>
</para>
@head:
-@cursor:
@Returns:
+@cursor:
<!-- ##### FUNCTION gras_dict_cursor_next ##### -->
<para>
</para>
-@dict:
@Returns:
+@dict:
<!-- ##### FUNCTION gras_dict_print ##### -->
<para>
</para>
-@whereto:
-@elm_size:
+@Param1:
@free_func:
@Returns:
+@whereto:
+@elm_size:
<!-- ##### FUNCTION gras_dynar_next ##### -->
<para>
</para>
@no_error: no error
-@malloc_error: Well known error
@mismatch_error: Not found
@system_error: a syscall did fail
@network_error: error while sending/receiving data
@msg:
-<!-- ##### FUNCTION gras_msg_handle ##### -->
-<para>
-
-</para>
-
-@timeOut:
-@Returns:
-
<!-- ##### FUNCTION gras_msg_new ##### -->
<para>
@Varargs:
@Returns:
-<!-- ##### FUNCTION gras_msg_send ##### -->
-<para>
-
-</para>
-
-@sock:
-@msgtype:
-@payload:
-@Returns:
-@sd:
-@msg:
-@freeDirective:
-
-<!-- ##### FUNCTION gras_msg_wait ##### -->
-<para>
-
-</para>
-
-@timeout:
-@msgt_want:
-@expeditor:
-@payload:
-@Returns:
-@id:
-@message:
-
-<!-- ##### FUNCTION gras_msgtype_by_name ##### -->
-<para>
-
-</para>
-
-@name:
-@Returns:
-@dst:
-
-<!-- ##### FUNCTION gras_msgtype_by_namev ##### -->
-<para>
-
-</para>
-
-@name:
-@version:
-@Returns:
-@dst:
-
-<!-- ##### FUNCTION gras_msgtype_declare ##### -->
-<para>
-
-</para>
-
-@name:
-@payload:
-@Returns:
-@dst:
-
-<!-- ##### FUNCTION gras_msgtype_declare_v ##### -->
-<para>
-
-</para>
-
-@name:
-@version:
-@payload:
-@Returns:
-@dst:
-
<!-- ##### FUNCTION gras_msgtype_register ##### -->
<para>
@Varargs:
@Returns:
-<!-- ##### FUNCTION gras_os_sleep ##### -->
-<para>
-
-</para>
-
-@Param1:
-@Param2:
-
-<!-- ##### FUNCTION gras_os_time ##### -->
-<para>
-
-</para>
-
-@Returns:
-
<!-- ##### FUNCTION gras_set_add ##### -->
<para>
</para>
-@dst:
@Returns:
+@dst:
<!-- ##### FUNCTION gras_sleep ##### -->
<para>
@sock:
@Returns:
-<!-- ##### FUNCTION gras_socket_client ##### -->
-<para>
-
-</para>
-
-@host:
-@Param2:
-@dst:
-@Returns:
-@bufSize:
-@sock:
-
-<!-- ##### FUNCTION gras_socket_close ##### -->
-<para>
-
-</para>
-
-@sd:
-@sock:
-@Returns:
-
-<!-- ##### FUNCTION gras_socket_my_port ##### -->
-<para>
-
-</para>
-
-@sock:
-@Returns:
-
-<!-- ##### FUNCTION gras_socket_peer_name ##### -->
-<para>
-
-</para>
-
-@sock:
-@Returns:
-@sd:
-
-<!-- ##### FUNCTION gras_socket_peer_port ##### -->
-<para>
-
-</para>
-
-@sock:
-@Returns:
-
-<!-- ##### FUNCTION gras_socket_server ##### -->
-<para>
-
-</para>
-
-@Param1:
-@dst:
-@Returns:
-@bufSize:
-
<!-- ##### FUNCTION gras_time ##### -->
<para>
@Returns:
-<!-- ##### FUNCTION gras_userdata_get ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### MACRO gras_userdata_new ##### -->
-<para>
-
-</para>
-
-@type:
-
-<!-- ##### FUNCTION gras_userdata_set ##### -->
+<!-- ##### ENUM xbt_error_t ##### -->
<para>
</para>
-@ud:
+@no_error:
+@mismatch_error:
+@system_error:
+@network_error:
+@timeout_error:
+@thread_error:
+@unknown_error:
+@remote_mismatch_error:
+@remote_system_error:
+@remote_network_error:
+@remote_timeout_error:
+@remote_thread_error:
+@remote_unknown_error:
