Iface.h 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178
  1. /* vim: set expandtab ts=4 sw=4: */
  2. /*
  3. * You may redistribute this program and/or modify it under the terms of
  4. * the GNU General Public License as published by the Free Software Foundation,
  5. * either version 3 of the License, or (at your option) any later version.
  6. *
  7. * This program is distributed in the hope that it will be useful,
  8. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  9. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  10. * GNU General Public License for more details.
  11. *
  12. * You should have received a copy of the GNU General Public License
  13. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  14. */
  15. #ifndef Iface_H
  16. #define Iface_H
  17. #include <stdint.h>
  18. #include "wire/Message.h"
  19. #include "util/Defined.h"
  20. struct Iface;
  21. /**
  22. * @param thisInterface the interface which contains the sendMessage function pointer.
  23. * @param message the message
  24. */
  25. typedef struct Iface* (* Iface_Callback)(struct Message* message, struct Iface* thisInterface);
  26. #define Iface_DEFUN __attribute__ ((warn_unused_result)) struct Iface*
  27. struct Iface
  28. {
  29. /** Send a message through this interface. */
  30. Iface_Callback send;
  31. #ifdef PARANOIA
  32. /** This is for checking currentMsg Iface_next() has not been called incorrectly. */
  33. struct Message* currentMsg;
  34. #endif
  35. /** Interface to which this one is connected (if connected) */
  36. struct Iface* connectedIf;
  37. };
  38. /**
  39. * Send a message to an Iface.
  40. * Whatever interface has been *plumbed* to this interface using Iface_plumb() will receive
  41. * the message. If you are in an Iface_Callback function, you must not use this function to
  42. * forward the message which you have received as your input, to do so will cause a runtime
  43. * assertion error, in order to forward the message which you received, you must use Iface_next()
  44. * and it must be a tail-call.
  45. */
  46. static inline void Iface_send(struct Iface* iface, struct Message* msg)
  47. {
  48. do {
  49. struct Iface* conn = iface->connectedIf;
  50. #ifdef PARANOIA
  51. Assert_true(conn);
  52. Assert_true(conn->send);
  53. Assert_true(msg);
  54. struct Message* currentMsg = conn->currentMsg;
  55. msg->currentIface = conn;
  56. conn->currentMsg = msg;
  57. #endif
  58. iface = conn->send(msg, conn);
  59. #ifdef PARANOIA
  60. msg->currentIface = NULL;
  61. conn->currentMsg = currentMsg;
  62. #endif
  63. if (!Defined(Iface_OPTIMIZE)) {
  64. Assert_true(!iface);
  65. }
  66. } while (iface);
  67. }
  68. /**
  69. * Forward a message from inside of an Iface_Callback function.
  70. * This function must be a tail-call, you must return the value returned to you.
  71. * If you do anything between the call to this function and your return of it's return value,
  72. * the order in which that thing happens is undefined.
  73. *
  74. * Consider the following (bad) code:
  75. * struct Iface* retVal = Iface_next(iface, msg);
  76. * x++;
  77. * return retVal;
  78. *
  79. * If Iface_OPTIMIZE is enabled, it becomes equivilant to:
  80. * x++;
  81. * struct Iface* retVal = Iface_next(iface, msg);
  82. * return retVal;
  83. *
  84. * So simplify your life and follow the basic rule of always returning directly the value
  85. * from this function, IE: return Iface_next(iface, msg);
  86. */
  87. static inline Iface_DEFUN Iface_next(struct Iface* iface, struct Message* msg)
  88. {
  89. #ifdef PARANOIA
  90. struct Iface* conn = iface->connectedIf;
  91. struct Message* currentMsg = conn->currentMsg;
  92. Assert_true(msg->currentIface);
  93. Assert_true(msg->currentIface->currentMsg == msg);
  94. msg->currentIface->currentMsg = NULL;
  95. #endif
  96. if (Defined(Iface_OPTIMIZE)) {
  97. #ifdef PARANOIA
  98. msg->currentIface = conn;
  99. conn->currentMsg = msg;
  100. #endif
  101. return iface;
  102. }
  103. #ifdef PARANOIA
  104. // done inside of Iface_send()
  105. msg->currentIface = NULL;
  106. conn->currentMsg = NULL;
  107. #endif
  108. Iface_send(iface, msg);
  109. #ifdef PARANOIA
  110. conn->currentMsg = currentMsg;
  111. #endif
  112. return NULL;
  113. }
  114. /**
  115. * Call a function which might use Iface_next()
  116. * This macro will call a function, passing it a message and other arguments, if the function
  117. * you are calling might use Iface_next(), you must call it with this macro instead of calling
  118. * it directly.
  119. * If you are calling from a Iface_Callback function, you must not use this function to call
  120. * the next function with the message passed to you. In that case just call the function directly.
  121. */
  122. #ifdef PARANOIA
  123. #define Iface_CALL(func, msg, ...) \
  124. do { \
  125. Assert_true(!msg->currentIface); \
  126. struct Iface Iface_y = { .currentMsg = msg }; \
  127. msg->currentIface = &Iface_y; \
  128. struct Iface* Iface_x = func(msg, __VA_ARGS__); \
  129. msg->currentIface = NULL; \
  130. if (Iface_x) { Iface_send(Iface_x, msg); } \
  131. } while (0)
  132. // CHECKFILES_IGNORE missing ;
  133. #else
  134. #define Iface_CALL(func, msg, ...) \
  135. do { \
  136. struct Iface* Iface_x = func(msg, __VA_ARGS__); \
  137. if (Iface_x) { Iface_send(Iface_x, msg); } \
  138. } while (0)
  139. // CHECKFILES_IGNORE missing ;
  140. #endif
  141. static inline void Iface_plumb(struct Iface* a, struct Iface* b)
  142. {
  143. Assert_true(!a->connectedIf);
  144. Assert_true(!b->connectedIf);
  145. a->connectedIf = b;
  146. b->connectedIf = a;
  147. }
  148. static inline void Iface_unplumb(struct Iface* a, struct Iface* b)
  149. {
  150. Assert_true(a->connectedIf == b);
  151. Assert_true(b->connectedIf == a);
  152. a->connectedIf = NULL;
  153. b->connectedIf = NULL;
  154. }
  155. #endif