libwebsockets
Lightweight C library for HTML5 websockets
lws-timeout-timer.h
Go to the documentation of this file.
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  */
24 
25 /*! \defgroup timeout Connection timeouts
26 
27  APIs related to setting connection timeouts
28 */
29 //@{
30 
31 #if defined(STANDALONE)
32 struct lws_context_standalone;
33 #define lws_context lws_context_standalone
34 #endif
35 
36 /*
37  * NOTE: These public enums are part of the abi. If you want to add one,
38  * add it at where specified so existing users are unaffected.
39  */
74 
75  /****** add new things just above ---^ ******/
76 
78 };
79 
80 #define lws_time_in_microseconds lws_now_usecs
81 
82 #define LWS_TO_KILL_ASYNC -1
83 /**< If LWS_TO_KILL_ASYNC is given as the timeout sec in a lws_set_timeout()
84  * call, then the connection is marked to be killed at the next timeout
85  * check. This is how you should force-close the wsi being serviced if
86  * you are doing it outside the callback (where you should close by nonzero
87  * return).
88  */
89 #define LWS_TO_KILL_SYNC -2
90 /**< If LWS_TO_KILL_SYNC is given as the timeout sec in a lws_set_timeout()
91  * call, then the connection is closed before returning (which may delete
92  * the wsi). This should only be used where the wsi being closed is not the
93  * wsi currently being serviced.
94  */
95 /**
96  * lws_set_timeout() - marks the wsi as subject to a timeout some seconds hence
97  *
98  * \param wsi: Websocket connection instance
99  * \param reason: timeout reason
100  * \param secs: how many seconds. You may set to LWS_TO_KILL_ASYNC to
101  * force the connection to timeout at the next opportunity, or
102  * LWS_TO_KILL_SYNC to close it synchronously if you know the
103  * wsi is not the one currently being serviced.
104  */
105 LWS_VISIBLE LWS_EXTERN void
106 lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
107 
108 /**
109  * lws_set_timeout_us() - marks the wsi as subject to a timeout some us hence
110  *
111  * \param wsi: Websocket connection instance
112  * \param reason: timeout reason
113  * \param us: 0 removes the timeout, otherwise number of us to wait
114  *
115  * Higher-resolution version of lws_set_timeout(). Actual resolution depends
116  * on platform and load, usually ms.
117  */
118 void
119 lws_set_timeout_us(struct lws *wsi, enum pending_timeout reason, lws_usec_t us);
120 
121 /* helper for clearer LWS_TO_KILL_ASYNC / LWS_TO_KILL_SYNC usage */
122 #define lws_wsi_close(w, to_kill) lws_set_timeout(w, 1, to_kill)
123 
124 
125 #define LWS_SET_TIMER_USEC_CANCEL ((lws_usec_t)-1ll)
126 #define LWS_USEC_PER_SEC ((lws_usec_t)1000000)
127 
128 /**
129  * lws_set_timer_usecs() - schedules a callback on the wsi in the future
130  *
131  * \param wsi: Websocket connection instance
132  * \param usecs: LWS_SET_TIMER_USEC_CANCEL removes any existing scheduled
133  * callback, otherwise number of microseconds in the future
134  * the callback will occur at.
135  *
136  * NOTE: event loop support for this:
137  *
138  * default poll() loop: yes
139  * libuv event loop: yes
140  * libev: not implemented (patch welcome)
141  * libevent: not implemented (patch welcome)
142  *
143  * After the deadline expires, the wsi will get a callback of type
144  * LWS_CALLBACK_TIMER and the timer is exhausted. The deadline may be
145  * continuously deferred by further calls to lws_set_timer_usecs() with a later
146  * deadline, or cancelled by lws_set_timer_usecs(wsi, -1).
147  *
148  * If the timer should repeat, lws_set_timer_usecs() must be called again from
149  * LWS_CALLBACK_TIMER.
150  *
151  * Accuracy depends on the platform and the load on the event loop or system...
152  * all that's guaranteed is the callback will come after the requested wait
153  * period.
154  */
155 LWS_VISIBLE LWS_EXTERN void
156 lws_set_timer_usecs(struct lws *wsi, lws_usec_t usecs);
157 
158 struct lws_sorted_usec_list;
159 
160 typedef void (*sul_cb_t)(struct lws_sorted_usec_list *sul);
161 
162 typedef struct lws_sorted_usec_list {
163  struct lws_dll2 list; /* simplify the code by keeping this at start */
166  uint32_t latency_us; /* us it may safely be delayed */
167 } lws_sorted_usec_list_t;
168 
169 /*
170  * There are multiple sul owners to allow accounting for, a) events that must
171  * wake from suspend, and b) events that can be missued due to suspend
172  */
173 #define LWS_COUNT_PT_SUL_OWNERS 2
174 
175 #define LWSSULLI_MISS_IF_SUSPENDED 0
176 #define LWSSULLI_WAKE_IF_SUSPENDED 1
177 
178 /*
179  * lws_sul2_schedule() - schedule a callback
180  *
181  * \param context: the lws_context
182  * \param tsi: the thread service index (usually 0)
183  * \param flags: LWSSULLI_...
184  * \param sul: pointer to the sul element
185  *
186  * Generic callback-at-a-later time function. The callback happens on the
187  * event loop thread context.
188  *
189  * Although the api has us resultion, the actual resolution depends on the
190  * platform and may be, eg, 1ms.
191  *
192  * This doesn't allocate and doesn't fail.
193  *
194  * If flags contains LWSSULLI_WAKE_IF_SUSPENDED, the scheduled event is placed
195  * on a sul owner list that, if the system has entered low power suspend mode,
196  * tries to arrange that the system should wake from platform suspend just
197  * before the event is due. Scheduled events without this flag will be missed
198  * in the case the system is in suspend and nothing else happens to have woken
199  * it.
200  *
201  * You can call it again with another us value to change the delay or move the
202  * event to a different owner (ie, wake or miss on suspend).
203  */
204 LWS_VISIBLE LWS_EXTERN void
205 lws_sul2_schedule(struct lws_context *context, int tsi, int flags,
206  lws_sorted_usec_list_t *sul);
207 
208 /*
209  * lws_sul_cancel() - cancel scheduled callback
210  *
211  * \param sul: pointer to the sul element
212  *
213  * If it's scheduled, remove the sul from its owning sorted list.
214  * If not scheduled, it's a NOP.
215  */
216 LWS_VISIBLE LWS_EXTERN void
217 lws_sul_cancel(lws_sorted_usec_list_t *sul);
218 
219 /*
220  * lws_sul_earliest_wakeable_event() - get earliest wake-from-suspend event
221  *
222  * \param ctx: the lws context
223  * \param pearliest: pointer to lws_usec_t to take the result
224  *
225  * Either returns 1 if no pending event, or 0 and sets *pearliest to the
226  * MONOTONIC time of the current earliest next expected event.
227  */
228 LWS_VISIBLE LWS_EXTERN int
229 lws_sul_earliest_wakeable_event(struct lws_context *ctx, lws_usec_t *pearliest);
230 
231 /*
232  * For backwards compatibility
233  *
234  * If us is LWS_SET_TIMER_USEC_CANCEL, the sul is removed from the scheduler.
235  * New code can use lws_sul_cancel()
236  */
237 
238 LWS_VISIBLE LWS_EXTERN void
239 lws_sul_schedule(struct lws_context *ctx, int tsi, lws_sorted_usec_list_t *sul,
240  sul_cb_t _cb, lws_usec_t _us);
241 LWS_VISIBLE LWS_EXTERN void
242 lws_sul_schedule_wakesuspend(struct lws_context *ctx, int tsi,
243  lws_sorted_usec_list_t *sul, sul_cb_t _cb,
244  lws_usec_t _us);
245 
246 #if defined(LWS_WITH_SUL_DEBUGGING)
247 /**
248  * lws_sul_debug_zombies() - assert there are no scheduled sul in a given object
249  *
250  * \param ctx: lws_context
251  * \param po: pointer to the object that is about to be destroyed
252  * \param len: length of the object that is about to be destroyed
253  * \param destroy_description: string clue what any failure is related to
254  *
255  * This is an optional debugging helper that walks the sul scheduler lists
256  * confirming that there are no suls scheduled that live inside the object
257  * footprint described by po and len. When internal objects are about to be
258  * destroyed, like wsi / user_data or secure stream handles, if
259  * LWS_WITH_SUL_DEBUGGING is enabled the scheduler is checked for anything
260  * in the object being destroyed. If something found, an error is printed and
261  * an assert fired.
262  *
263  * Internal sul like timeouts should always be cleaned up correctly, but user
264  * suls in, eg, wsi user_data area, or in secure stream user allocation, may be
265  * the cause of difficult to find bugs if valgrind not available and the user
266  * code left a sul in the scheduler after destroying the object the sul was
267  * living in.
268  */
269 LWS_VISIBLE LWS_EXTERN void
270 lws_sul_debug_zombies(struct lws_context *ctx, void *po, size_t len,
271  const char *destroy_description);
272 #else
273 #define lws_sul_debug_zombies(_a, _b, _c, _d)
274 #endif
275 
276 /*
277  * lws_validity_confirmed() - reset the validity timer for a network connection
278  *
279  * \param wsi: the connection that saw traffic proving the connection valid
280  *
281  * Network connections are subject to intervals defined by the context, the
282  * vhost if server connections, or the client connect info if a client
283  * connection. If the connection goes longer than the specified time since
284  * last observing traffic that can only happen if traffic is passing in both
285  * directions, then lws will try to create a PING transaction on the network
286  * connection.
287  *
288  * If the connection reaches the specified `.secs_since_valid_hangup` time
289  * still without any proof of validity, the connection will be closed.
290  *
291  * If the PONG comes, or user code observes traffic that satisfies the proof
292  * that both directions are passing traffic to the peer and calls this api,
293  * the connection validity timer is reset and the scheme repeats.
294  */
295 LWS_VISIBLE LWS_EXTERN void
296 lws_validity_confirmed(struct lws *wsi);
297 
298 /*
299  * These are not normally needed, they're exported for the case there's code
300  * using lws_sul for which lws is an optional link dependency.
301  */
302 
303 LWS_VISIBLE LWS_EXTERN int
304 __lws_sul_insert(lws_dll2_owner_t *own, lws_sorted_usec_list_t *sul);
305 
306 LWS_VISIBLE LWS_EXTERN lws_usec_t
307 __lws_sul_service_ripe(lws_dll2_owner_t *own, int own_len, lws_usec_t usnow);
308 
309 #if defined(STANDALONE)
310 #undef lws_context
311 #endif
312 
313 ///@}