libwebsockets
Lightweight C library for HTML5 websockets
lws-retry.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 typedef struct lws_retry_bo {
26  const uint32_t *retry_ms_table; /* base delay in ms */
27  uint16_t retry_ms_table_count; /* entries in table */
28  uint16_t conceal_count; /* max retries to conceal */
29  uint16_t secs_since_valid_ping; /* idle before PING issued */
30  uint16_t secs_since_valid_hangup; /* idle before hangup conn */
31  uint8_t jitter_percent; /* % additional random jitter */
32 } lws_retry_bo_t;
33 
34 #define LWS_RETRY_CONCEAL_ALWAYS (0xffff)
35 
36 /**
37  * lws_retry_get_delay_ms() - get next delay from backoff table
38  *
39  * \param lws_context: the lws context (used for getting random)
40  * \param retry: the retry backoff table we are using, or NULL for default
41  * \param ctry: pointer to the try counter
42  * \param conceal: pointer to flag set to nonzero if the try should be concealed
43  * in terms of creating an error
44  *
45  * Increments *\p try and retruns the number of ms that should elapse before the
46  * next connection retry, according to the backoff table \p retry. *\p conceal is
47  * set if the number of tries is less than the backoff table conceal_count, or
48  * is zero if it exceeded it. This lets you conceal a certain number of retries
49  * before alerting the caller there is a problem.
50  *
51  * If \p retry is NULL, a default of 3s + (0..300ms jitter) is used. If it's
52  * non-NULL but jitter_percent is 0, the default of 30% jitter is retained.
53  */
54 
55 LWS_VISIBLE LWS_EXTERN unsigned int
56 lws_retry_get_delay_ms(struct lws_context *context, const lws_retry_bo_t *retry,
57  uint16_t *ctry, char *conceal);
58 
59 /**
60  * lws_retry_sul_schedule() - schedule a sul according to the backoff table
61  *
62  * \param lws_context: the lws context (used for getting random)
63  * \param sul: pointer to the sul to schedule
64  * \param retry: the retry backoff table we are using, or NULL for default
65  * \param cb: the callback for when the sul schedule time arrives
66  * \param ctry: pointer to the try counter
67  *
68  * Helper that combines interpreting the retry table with scheduling a sul to
69  * the computed delay. If conceal is not set, it will not schedule the sul
70  * and just return 1. Otherwise the sul is scheduled and it returns 0.
71  */
72 LWS_VISIBLE LWS_EXTERN int
73 lws_retry_sul_schedule(struct lws_context *context, int tid,
74  lws_sorted_usec_list_t *sul, const lws_retry_bo_t *retry,
75  sul_cb_t cb, uint16_t *ctry);
76 
77 /**
78  * lws_retry_sul_schedule_retry_wsi() - retry sul schedule helper using wsi
79  *
80  * \param wsi: the wsi to set the hrtimer sul on to the next retry interval
81  * \param sul: pointer to the sul to schedule
82  * \param cb: the callback for when the sul schedule time arrives
83  * \param ctry: pointer to the try counter
84  *
85  * Helper that uses context, tid and retry policy from a wsi to call
86  * lws_retry_sul_schedule.
87  *
88  * Since a udp connection can have many writes in flight, the retry count and
89  * the sul used to track each thing that wants to be written have to be handled
90  * individually, not the wsi. But the retry policy and the other things can
91  * be filled in from the wsi conveniently.
92  */
93 LWS_VISIBLE LWS_EXTERN int
94 lws_retry_sul_schedule_retry_wsi(struct lws *wsi, lws_sorted_usec_list_t *sul,
95  sul_cb_t cb, uint16_t *ctry);