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 <https://www.gnu.org/licenses/>.
14 */
15 #ifndef Iface_H
16 #define Iface_H
17
18 #include <stdint.h>
19
20 #include "wire/Message.h"
21 #include "util/Defined.h"
22
23 struct Iface;
24
25 /**
26 * @param thisInterface the interface which contains the sendMessage function pointer.
27 * @param message the message
28 */
29 typedef struct Iface* (* Iface_Callback)(struct Message* message, struct Iface* thisInterface);
30
31 #define Iface_DEFUN __attribute__ ((warn_unused_result)) struct Iface*
32
33 struct Iface
34 {
35 /** Send a message through this interface. */
36 Iface_Callback send;
37
38 #ifdef PARANOIA
39 /** This is for checking currentMsg Iface_next() has not been called incorrectly. */
40 struct Message* currentMsg;
41 #endif
42
43 /** Interface to which this one is connected (if connected) */
44 struct Iface* connectedIf;
45 };
46
47 /**
48 * Send a message to an Iface.
49 * Whatever interface has been *plumbed* to this interface using Iface_plumb() will receive
50 * the message. If you are in an Iface_Callback function, you must not use this function to
51 * forward the message which you have received as your input, to do so will cause a runtime
52 * assertion error, in order to forward the message which you received, you must use Iface_next()
53 * and it must be a tail-call.
54 */
Iface_send(struct Iface * iface,struct Message * msg)55 static inline void Iface_send(struct Iface* iface, struct Message* msg)
56 {
57 do {
58 struct Iface* conn = iface->connectedIf;
59
60 #ifdef PARANOIA
61 Assert_true(conn);
62 Assert_true(conn->send);
63 Assert_true(msg);
64 struct Message* currentMsg = conn->currentMsg;
65 msg->currentIface = conn;
66 conn->currentMsg = msg;
67 #endif
68
69 iface = conn->send(msg, conn);
70
71 #ifdef PARANOIA
72 msg->currentIface = NULL;
73 conn->currentMsg = currentMsg;
74 #endif
75
76 if (!Defined(Iface_OPTIMIZE)) {
77 Assert_true(!iface);
78 }
79 } while (iface);
80 }
81
82 /**
83 * Forward a message from inside of an Iface_Callback function.
84 * This function must be a tail-call, you must return the value returned to you.
85 * If you do anything between the call to this function and your return of it's return value,
86 * the order in which that thing happens is undefined.
87 *
88 * Consider the following (bad) code:
89 * struct Iface* retVal = Iface_next(iface, msg);
90 * x++;
91 * return retVal;
92 *
93 * If Iface_OPTIMIZE is enabled, it becomes equivilant to:
94 * x++;
95 * struct Iface* retVal = Iface_next(iface, msg);
96 * return retVal;
97 *
98 * So simplify your life and follow the basic rule of always returning directly the value
99 * from this function, IE: return Iface_next(iface, msg);
100 */
Iface_next(struct Iface * iface,struct Message * msg)101 static inline Iface_DEFUN Iface_next(struct Iface* iface, struct Message* msg)
102 {
103 #ifdef PARANOIA
104 struct Iface* conn = iface->connectedIf;
105 struct Message* currentMsg = conn->currentMsg;
106 Assert_true(msg->currentIface);
107 Assert_true(msg->currentIface->currentMsg == msg);
108 msg->currentIface->currentMsg = NULL;
109 #endif
110
111 if (Defined(Iface_OPTIMIZE)) {
112 #ifdef PARANOIA
113 msg->currentIface = conn;
114 conn->currentMsg = msg;
115 #endif
116 return iface;
117 }
118
119 #ifdef PARANOIA
120 // done inside of Iface_send()
121 msg->currentIface = NULL;
122 conn->currentMsg = NULL;
123 #endif
124
125 Iface_send(iface, msg);
126
127 #ifdef PARANOIA
128 conn->currentMsg = currentMsg;
129 #endif
130
131 return NULL;
132 }
133
134 /**
135 * Call a function which might use Iface_next()
136 * This macro will call a function, passing it a message and other arguments, if the function
137 * you are calling might use Iface_next(), you must call it with this macro instead of calling
138 * it directly.
139 * If you are calling from a Iface_Callback function, you must not use this function to call
140 * the next function with the message passed to you. In that case just call the function directly.
141 *
142 * Why is there code using this weird function rather than simply calling Iface_send() ?
143 * Iface_send() only works when you send to *your* iface which is plumbed to the iface that you want
144 * the data to go to, this macro will be used when you want to bypass the need to create a local
145 * iface and plumb it to the remote one just in order to send one message.
146 */
147 #ifdef PARANOIA
148 #define Iface_CALL(func, msg, ...) \
149 do { \
150 Assert_true(!msg->currentIface); \
151 struct Iface Iface_y = { .currentMsg = msg }; \
152 msg->currentIface = &Iface_y; \
153 struct Iface* Iface_x = func(msg, __VA_ARGS__); \
154 msg->currentIface = NULL; \
155 if (Iface_x) { Iface_send(Iface_x, msg); } \
156 } while (0)
157 // CHECKFILES_IGNORE missing ;
158 #else
159 #define Iface_CALL(func, msg, ...) \
160 do { \
161 struct Iface* Iface_x = func(msg, __VA_ARGS__); \
162 if (Iface_x) { Iface_send(Iface_x, msg); } \
163 } while (0)
164 // CHECKFILES_IGNORE missing ;
165 #endif
166
Iface_plumb(struct Iface * a,struct Iface * b)167 static inline void Iface_plumb(struct Iface* a, struct Iface* b)
168 {
169 Assert_true(!a->connectedIf);
170 Assert_true(!b->connectedIf);
171 a->connectedIf = b;
172 b->connectedIf = a;
173 }
174
Iface_unplumb(struct Iface * a,struct Iface * b)175 static inline void Iface_unplumb(struct Iface* a, struct Iface* b)
176 {
177 Assert_true(a->connectedIf == b);
178 Assert_true(b->connectedIf == a);
179 a->connectedIf = NULL;
180 b->connectedIf = NULL;
181 }
182
183 #endif
184