tools/tesh2/include/unit.h

   1 /*\r
   2  * include/unit.h - type representing the tesh unit concept.\r
   3  *\r
   4  * Copyright 2008,2009 Martin Quinson, Malek Cherier All right reserved. \r
   5  *\r
   6  * This program is free software; you can redistribute it and/or modify it \r
   7  * under the terms of the license (GNU LGPL) which comes with this package.\r
   8  *\r
   9  * Purpose:\r
  10  *              This file contains all the declarations of the functions related with\r
  11  *              the tesh unit concept.\r
  12  *\r
  13  */\r
  14  \r
  15 #ifndef __UNIT_H        \r
  16 #define __UNIT_H\r
  17 \r
  18 #include <com.h>\r
  19 \r
  20 #ifdef __cplusplus\r
  21 extern "C" {\r
  22 #endif\r
  23 \r
  24 /*! \brief unit_new - create a new unit.\r
  25  *\r
  26  * \param runner        The runner which runs the unit.\r
  27  * \param owner         The unit which owns the unit if it is an included unit.\r
  28  * \param fstream       The file stream object used to parse the unit.\r
  29  *\r
  30  * \return                      If successful the function returns the newly created\r
  31  *                                      unit. Otherwise the function returns NULL and sets the\r
  32  *                                      global variable errno with the appropiate error code.\r
  33  *\r
  34  * errors :\r
  35  *                                      [EINVAL] if one of the parameters is invalid.\r
  36  *                                      [ENOMEM] if the system has not enough space to allocate\r
  37  *                                               the unit.\r
  38  */\r
  39 unit_t\r
  40 unit_new(runner_t runner, unit_t root, unit_t owner, fstream_t fstream);\r
  41 \r
  42 /*! \brief unit_free - destroy a tesh unit.\r
  43  *\r
  44  * \param ptr           A pointer to the unit to destroy.\r
  45  *\r
  46  * \return                      If successful the function returns 0. Otherwise the \r
  47  *                                      function returns -1 and sets the global variable errno \r
  48  *                                      with the appropiate error code.\r
  49  *\r
  50  * errors :\r
  51  *                                      [EINVAL] if the pointer to the unit to destroy is invalid.\r
  52  */\r
  53 int\r
  54 unit_free(unit_t* ptr);\r
  55 \r
  56 /*! \brief unit_run - run a tesh unit.\r
  57  *\r
  58  * \param unit          The unit to run.\r
  59  * \param mutex         A mutex used to synchronize the access of the runner properties.\r
  60  *\r
  61  * \return                      If successful the function returns 0. Otherwise the \r
  62  *                                      function returns -1 and sets the global variable errno \r
  63  *                                      with the appropiate error code.\r
  64  *\r
  65  * errors :\r
  66  *                                      [EINVAL] if the unit specified as parameter is invalid.\r
  67  *                                               if the mutex specified as parameter is invalid.\r
  68  *\r
  69  * remarks :            If the runner is interrupted during a call of this function,\r
  70  *                                      the unit is not launched but its flag interrupted is signaled.\r
  71  */\r
  72 int\r
  73 unit_run(unit_t unit, xbt_os_mutex_t mutex);\r
  74 \r
  75 \r
  76 /*! \brief unit_interrupt - interrupt a tesh unit.\r
  77  *\r
  78  * \param unit          The unit to interrupt.\r
  79  *\r
  80  * \return                      If successful the function returns 0. Otherwise the \r
  81  *                                      function returns -1 and sets the global variable errno \r
  82  *                                      with the appropiate error code.\r
  83  *\r
  84  * errors :\r
  85  *                                      [EINVAL] if the unit specified as parameter is invalid.\r
  86  *                                      [EALREADY] if the unit is already interrupted.\r
  87  *\r
  88  * remarks :            If the runner is interrupted during a call of this function,\r
  89  *                                      the unit is not launched but its flag interrupted is signaled.\r
  90  */\r
  91 int\r
  92 unit_interrupt(unit_t unit);\r
  93 \r
  94 /*! \brief unit_summuarize - summarize the run of tesh unit.\r
  95  *\r
  96  * \param unit          The unit to summarize the run.\r
  97  *\r
  98  * \return                      If successful the function returns 0. Otherwise the \r
  99  *                                      function returns -1 and sets the global variable errno \r
 100  *                                      with the appropiate error code.\r
 101  *\r
 102  * errors :\r
 103  *                                      [EINVAL] if the unit specified as parameter is invalid.\r
 104  */\r
 105 int\r
 106 unit_summuarize(unit_t unit);\r
 107 \r
 108 int\r
 109 unit_reset(unit_t unit);\r
 110 \r
 111 void\r
 112 unit_set_error(unit_t unit, int errcode, int kind);\r
 113 \r
 114 #ifdef __cplusplus\r
 115 }\r
 116 #endif\r
 117 \r
 118 \r
 119 #endif /* !__UNIT_H */\r