From: alegrand Date: Wed, 8 Dec 2004 19:48:35 +0000 (+0000) Subject: Renaming tbx to xbt and adding some of my functions. X-Git-Tag: v3.3~4788 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/a8926af1402150f829dc3b591625166c8720f6bf Renaming tbx to xbt and adding some of my functions. git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@562 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- diff --git a/cruft/doc/gras-docs.sgml b/cruft/doc/gras-docs.sgml index 6494aff844..6d1c556240 100644 --- a/cruft/doc/gras-docs.sgml +++ b/cruft/doc/gras-docs.sgml @@ -11,12 +11,16 @@ - - - - - - + + + + + + + + + + @@ -302,12 +306,19 @@ Write examples. GRAS toolbox - &tbx-err; - &tbx-log; - &tbx-dynar; - &tbx-dico; - &tbx-set; - &tbx-cfg; + &xbt-error; + &xbt-log; + &xbt-dynar; + &xbt-dict; + &xbt-set; + &xbt-swag; + &xbt-heap; + &xbt-config; + + + + SURF + &surf-maxmin; + + + + + + + + + + + + + + + + +Dynamic arrays + + @@ -428,6 +448,286 @@ Overview of the GRAS library Overview + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt.sgml + + + + + + + + + + + + + + + + + + + +./gras-sections.txt + + @@ -587,24 +887,640 @@ SG nws_comm - + - + - + +Configuration facilities. + +Config - -Sockets + + + + + + + + + + + + + + +Data container associating data to a string key. + + + +Dictionnary + + + + +This module provide the quite usual dynamic array facility. + + + + + + + + + + +Use arrays, forget about malloc + + + +Dynamic array + + + + + + + + + + + + + + + +Error reporting + + + +Errors handling + + + + + 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. + + + + Overview + + + There is 3 main concepts: category, priority and appender. These three + concepts work together to enable developers to log messages according to + message type and priority, and to control at runtime how these messages are + formatted and where they are reported. + + + + + Category hierarchy + + + The first and foremost advantage of any logging API over plain printf() + resides in its ability to disable certain log statements while allowing + others to print unhindered. This capability assumes that the logging space, + that is, the space of all possible logging statements, is categorized + according to some developer-chosen criteria. + + + + This observation led to choosing category as the central concept of the + system. Every category is declared by providing a name and an optional + parent. If no parent is explicitly named, the root category, LOG_ROOT_CAT + is the category's parent. + + + + A category is created by a macro call at the top level of a file. A + category can be created with any one of the following macros: + + + + + @GRAS_LOG_NEW_CATEGORY(MyCat); + create a new root + + + + @GRAS_LOG_NEW_SUBCATEGORY(MyCat, ParentCat); + Create a new category being child of the category ParentCat + + + + @GRAS_LOG_NEW_DEFAULT_CATEGORY(MyCat); + Like GRAS_LOG_NEW_CATEGORY, but the new category is the default one + in this file + + + + @GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, ParentCat); + Like GRAS_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, but each + category may have only one definition. + + + + Typically, there will be a Category for each module and sub-module, so you + can independently control logging for each module. + + + + + Priority + + + A category may be assigned a threshold priorty. The set of priorites are + defined by the @gras_log_priority_t enum. Their values are DEBUG, VERBOSE, + INFO, WARNING, ERROR and CRITICAL. + + + + 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. + 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: + + + CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5, "oops"); + + This is a logging request with priority WARN. + + + A logging request is said to be enabled if its priority is higher than or + equal to the threshold priority of its category. Otherwise, the request is + said to be disabled. A category without an assigned priority will inherit + one from the hierarchy. + + + + It is possible to use any non-negative integer as a priority. If, as in the + example, one of the standard priorites is used, then there is a convenience + macro that is typically used instead. For example, the above example is + equivalent to the shorter: + + + CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops"); + + + + Default category + + + If @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: + + + WARN3("Values are: %d and '%s'", 5, "oops"); + + + Only one default category can be created per file, though multiple + non-defaults can be created and used. + + + + + Example + + Here is a more complete example: + + + #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"); + } + + + + Configuration + + + 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. + + + + + Performance + + + Clever design insures efficiency. Except for the first invocation, a + disabled logging request requires an a single comparison of a static + variable to a constant. + + + + There is also compile time constant, @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". + + + + + Appenders + + + 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. + + + + 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, 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. + + + + 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. + + + + 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. + + + + + + + Misc and Caveats + + + Do not use any of the macros that start with '_'. + + + + 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. + + + + 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. + + + + + + + + + + + +An easy-to-use, fast and flexible message logging architecture. + + + +Logging facilities + + + + + + + + + + + + + + + +Data storage for very quick retrieve + + + +Data set + + + + + + + + + + + + + + + + + + + +Sockets + + + + + + + + + + + + + + + + + + + +xbt_cfg + + + + + + + + + + + + + + + + + + + +xbt_dico + + + + + + + + + + + + + + + + + + + +Errors + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml.sgml.sgml + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml.sgml + + + + + + + + + + + + + + + + + + + +xbt_swag.sgml diff --git a/cruft/doc/tmpl/tbx_cfg.sgml b/cruft/doc/tmpl/tbx_cfg.sgml deleted file mode 100644 index d6d7834d6a..0000000000 --- a/cruft/doc/tmpl/tbx_cfg.sgml +++ /dev/null @@ -1,16 +0,0 @@ - -Config - - -Configuration facilities. - - - - - - - - - - - diff --git a/cruft/doc/tmpl/tbx_dico.sgml b/cruft/doc/tmpl/tbx_dico.sgml deleted file mode 100644 index 0e59b654fa..0000000000 --- a/cruft/doc/tmpl/tbx_dico.sgml +++ /dev/null @@ -1,16 +0,0 @@ - -Dictionnary - - -Data container associating data to a string key. - - - - - - - - - - - diff --git a/cruft/doc/tmpl/tbx_dynar.sgml b/cruft/doc/tmpl/tbx_dynar.sgml deleted file mode 100644 index e02316ee69..0000000000 --- a/cruft/doc/tmpl/tbx_dynar.sgml +++ /dev/null @@ -1,16 +0,0 @@ - -Dynamic array - - -Use arrays, forget about malloc - - - -This module provide the quite usual dynamic array facility. - - - - - - - diff --git a/cruft/doc/tmpl/tbx_err.sgml b/cruft/doc/tmpl/tbx_err.sgml deleted file mode 100644 index e283b6a340..0000000000 --- a/cruft/doc/tmpl/tbx_err.sgml +++ /dev/null @@ -1,16 +0,0 @@ - -Errors handling - - -Error reporting - - - - - - - - - - - diff --git a/cruft/doc/tmpl/tbx_set.sgml b/cruft/doc/tmpl/tbx_set.sgml deleted file mode 100644 index ddb5d3598e..0000000000 --- a/cruft/doc/tmpl/tbx_set.sgml +++ /dev/null @@ -1,16 +0,0 @@ - -Data set - - -Data storage for very quick retrieve - - - - - - - - - - - diff --git a/cruft/doc/tmpl/xbt_config.sgml b/cruft/doc/tmpl/xbt_config.sgml new file mode 100644 index 0000000000..c7f6f0addb --- /dev/null +++ b/cruft/doc/tmpl/xbt_config.sgml @@ -0,0 +1,268 @@ + +Config + + +Configuration facilities. + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@tocopy: +@whereto: + + + + + + + +@cfg: + + + + + + + +@name: +@indent: +@cfg: + + + + + + + +@cfg: +@name: +@type: +@min: +@max: + + + + + + + +@cfg: +@entry: +@Returns: + + + + + + + +@cfg: +@Returns: + + + + + + + +@cfg: +@options: +@Returns: + + + + + + + +@cfg: +@Varargs: +@Returns: + + + + + + + +@cfg: +@pa: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@host: +@port: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@host: +@port: +@Returns: + + + + + + + +@cfg: +@name: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@val: +@Returns: + + + + + + + +@cfg: +@name: +@host: +@port: +@Returns: + + + + + + + +@cfg: +@name: +@dynar: +@Returns: + + diff --git a/cruft/doc/tmpl/xbt_dico.sgml b/cruft/doc/tmpl/xbt_dico.sgml new file mode 100644 index 0000000000..552b162e4a --- /dev/null +++ b/cruft/doc/tmpl/xbt_dico.sgml @@ -0,0 +1,180 @@ + +xbt_dico + + + + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@dict: + + + + + + + +@head: +@key: +@data: +@free_ctn: + + + + + + + +@head: +@key: +@key_len: +@data: +@free_ctn: + + + + + + + +@head: +@key: +@data: +@Returns: + + + + + + + +@head: +@key: +@key_len: +@data: +@Returns: + + + + + + + +@head: +@key: +@Returns: + + + + + + + +@head: +@key: +@key_len: +@Returns: + + + + + + + +@head: +@output: + + + + + + + +@data: + + + + + + + +@data: + + + + + + + +@cursor: +@data: +@Returns: + + + + + + + +@cursor: +@key: +@Returns: + + + + + + + +@dict: +@cursor: +@key: +@data: + + + + + + + +@head: +@Returns: + + + + + + + +@cursor: + + + + + + + +@cursor: + + diff --git a/cruft/doc/tmpl/xbt_dict.sgml b/cruft/doc/tmpl/xbt_dict.sgml new file mode 100644 index 0000000000..d5217fc480 --- /dev/null +++ b/cruft/doc/tmpl/xbt_dict.sgml @@ -0,0 +1,180 @@ + +Dictionaries + + +Data container associating data to a string key. + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@dict: + + + + + + + +@head: +@key: +@data: +@free_ctn: + + + + + + + +@head: +@key: +@key_len: +@data: +@free_ctn: + + + + + + + +@head: +@key: +@data: +@Returns: + + + + + + + +@head: +@key: +@key_len: +@data: +@Returns: + + + + + + + +@head: +@key: +@Returns: + + + + + + + +@head: +@key: +@key_len: +@Returns: + + + + + + + +@head: +@output: + + + + + + + +@data: + + + + + + + +@data: + + + + + + + +@cursor: +@data: +@Returns: + + + + + + + +@cursor: +@key: +@Returns: + + + + + + + +@dict: +@cursor: +@key: +@data: + + + + + + + +@head: +@Returns: + + + + + + + +@cursor: + + + + + + + +@cursor: + + diff --git a/cruft/doc/tmpl/xbt_dynar.sgml b/cruft/doc/tmpl/xbt_dynar.sgml new file mode 100644 index 0000000000..fb88956c5d --- /dev/null +++ b/cruft/doc/tmpl/xbt_dynar.sgml @@ -0,0 +1,192 @@ + +Dynamic array + + +Use arrays, forget about malloc + + + +This module provide the quite usual dynamic array facility. + + + + + + + + + + + + +@Param1: +@free_func: +@Returns: + + + + + + + +@dynar: + + + + + + + +@dynar: + + + + + + + +@dynar: +@Returns: + + + + + + + +@dynar: + + + + + + + +@dynar: +@idx: +@src: + + + + + + + +@dynar: +@idx: +@object: + + + + + + + +@dynar: +@idx: +@src: + + + + + + + +@dynar: +@idx: +@object: + + + + + + + +@dynar: +@operator: + + + + + + + +@dynar: +@src: + + + + + + + +@dynar: +@dst: + + + + + + + +@dynar: +@dst: + + + + + + + +@dynar: +@src: + + + + + + + +@_dynar: +@_cursor: +@_data: + + + + + + + +@dynar: +@cursor: + + + + + + + +@dynar: +@cursor: + + + + + + + +@dynar: +@cursor: +@whereto: +@Returns: + + + + + + + +@dynar: +@cursor: + + diff --git a/cruft/doc/tmpl/xbt_error.sgml b/cruft/doc/tmpl/xbt_error.sgml new file mode 100644 index 0000000000..8ce9735f7f --- /dev/null +++ b/cruft/doc/tmpl/xbt_error.sgml @@ -0,0 +1,35 @@ + +Errors handling + + +Error reporting + + + + + + + + + + + + + + + + +@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: + diff --git a/cruft/doc/tmpl/xbt_heap.sgml b/cruft/doc/tmpl/xbt_heap.sgml new file mode 100644 index 0000000000..f34856d305 --- /dev/null +++ b/cruft/doc/tmpl/xbt_heap.sgml @@ -0,0 +1,78 @@ + +Heap + + +A simple heap with O(log(n)) access. + + + + + + + + + + + + + + + + +@num: +@free_func: +@Returns: + + + + + + + +@H: + + + + + + + +@H: +@Returns: + + + + + + + +@H: +@content: +@key: + + + + + + + +@H: + + + + + + + +@H: +@Returns: + + + + + + + +@H: + + diff --git a/cruft/doc/tmpl/tbx_log.sgml b/cruft/doc/tmpl/xbt_log.sgml similarity index 91% rename from cruft/doc/tmpl/tbx_log.sgml rename to cruft/doc/tmpl/xbt_log.sgml index bde7ca98a9..09091fc996 100644 --- a/cruft/doc/tmpl/tbx_log.sgml +++ b/cruft/doc/tmpl/xbt_log.sgml @@ -5,7 +5,7 @@ Logging facilities An easy-to-use, fast and flexible message logging architecture. - + 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, @@ -290,6 +290,99 @@ An easy-to-use, fast and flexible message logging architecture. + + + + + +@cs: + + + + + + + +@catName: +@desc: + + + + + + + +@catName: +@parent: +@desc: + + + + + + + +@cname: +@desc: + + + + + + + +@cname: +@parent: +@desc: + + + + + + + +@cname: + + + + + + + +@cname: + + + + + + + +@catName: +@priority: + + + + + + + + + + + + + + +@cat: +@app: + + + + + + + + diff --git a/cruft/doc/tmpl/xbt_set.sgml b/cruft/doc/tmpl/xbt_set.sgml new file mode 100644 index 0000000000..a7737fb243 --- /dev/null +++ b/cruft/doc/tmpl/xbt_set.sgml @@ -0,0 +1,86 @@ + +Data set based on dictionnaries + + +Data storage for very quick retrieve + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@set: + + + + + + + +@set: +@elm: +@free_func: + + + + + + + +@set: +@key: +@dst: +@Returns: + + + + + + + +@set: +@name: +@name_len: +@dst: +@Returns: + + + + + + + +@set: +@id: +@dst: +@Returns: + + + + + + + +@set: +@cursor: +@elm: + + diff --git a/cruft/doc/tmpl/xbt_swag.sgml b/cruft/doc/tmpl/xbt_swag.sgml new file mode 100644 index 0000000000..2119f6dc28 --- /dev/null +++ b/cruft/doc/tmpl/xbt_swag.sgml @@ -0,0 +1,117 @@ + +Swag + + +valuable goods : 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. + + + + + + + + + + + + +@offset: +@Returns: + + + + + + + +@swag: + + + + + + + +@swag: +@offset: + + + + + + + +@obj: +@swag: + + + + + + + +@obj: +@swag: + + + + + + + +@swag: + + + + + + + +@swag: +@Returns: + + + + + + + +@obj: +@swag: +@Returns: + + + + + + + +@obj: +@swag: + + + + + + + +@obj: +@obj_next: +@swag: + + + + + + + +@var: +@field: + +