libwebsockets
Lightweight C library for HTML5 websockets
lws-timeout-timer.h
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 
30 
31 #if defined(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  */
40 enum pending_timeout {
41  NO_PENDING_TIMEOUT = 0,
42  PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE = 1,
43  PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE = 2,
44  PENDING_TIMEOUT_ESTABLISH_WITH_SERVER = 3,
45  PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE = 4,
46  PENDING_TIMEOUT_AWAITING_PING = 5,
47  PENDING_TIMEOUT_CLOSE_ACK = 6,
48  PENDING_TIMEOUT_UNUSED1 = 7,
49  PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE = 8,
50  PENDING_TIMEOUT_SSL_ACCEPT = 9,
51  PENDING_TIMEOUT_HTTP_CONTENT = 10,
52  PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND = 11,
53  PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE = 12,
54  PENDING_TIMEOUT_SHUTDOWN_FLUSH = 13,
55  PENDING_TIMEOUT_CGI = 14,
56  PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE = 15,
57  PENDING_TIMEOUT_WS_PONG_CHECK_SEND_PING = 16,
58  PENDING_TIMEOUT_WS_PONG_CHECK_GET_PONG = 17,
59  PENDING_TIMEOUT_CLIENT_ISSUE_PAYLOAD = 18,
60  PENDING_TIMEOUT_AWAITING_SOCKS_GREETING_REPLY = 19,
61  PENDING_TIMEOUT_AWAITING_SOCKS_CONNECT_REPLY = 20,
62  PENDING_TIMEOUT_AWAITING_SOCKS_AUTH_REPLY = 21,
63  PENDING_TIMEOUT_KILLED_BY_SSL_INFO = 22,
64  PENDING_TIMEOUT_KILLED_BY_PARENT = 23,
65  PENDING_TIMEOUT_CLOSE_SEND = 24,
66  PENDING_TIMEOUT_HOLDING_AH = 25,
67  PENDING_TIMEOUT_UDP_IDLE = 26,
68  PENDING_TIMEOUT_CLIENT_CONN_IDLE = 27,
69  PENDING_TIMEOUT_LAGGING = 28,
70  PENDING_TIMEOUT_THREADPOOL = 29,
71  PENDING_TIMEOUT_THREADPOOL_TASK = 30,
72  PENDING_TIMEOUT_KILLED_BY_PROXY_CLIENT_CLOSE = 31,
73  PENDING_TIMEOUT_USER_OK = 32,
74 
75  /****** add new things just above ---^ ******/
76 
77  PENDING_TIMEOUT_USER_REASON_BASE = 1000
78 };
79 
80 #define lws_time_in_microseconds lws_now_usecs
81 
82 #define LWS_TO_KILL_ASYNC -1
89 #define LWS_TO_KILL_SYNC -2
105 LWS_VISIBLE LWS_EXTERN void
106 lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
107 
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 
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 */
164  lws_usec_t us;
165  sul_cb_t cb;
166  uint32_t latency_us; /* us it may safely be delayed */
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,
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)
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 
Definition: lws-secure-streams-client.h:190
Definition: lws-dll2.h:203
Definition: lws-dll2.h:197
Definition: lws-timeout-timer.h:162