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
25typedef 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
55LWS_VISIBLE LWS_EXTERN unsigned int
56lws_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 */
72LWS_VISIBLE LWS_EXTERN int
73lws_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 */
93LWS_VISIBLE LWS_EXTERN int
94lws_retry_sul_schedule_retry_wsi(struct lws *wsi, lws_sorted_usec_list_t *sul,
95 sul_cb_t cb, uint16_t *ctry);
96