libwebsockets
Lightweight C library for HTML5 websockets
lws-sequencer.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 * lws_sequencer is intended to help implement sequences that:
25 *
26 * - outlive a single connection lifetime,
27 * - are not associated with a particular protocol,
28 * - are not associated with a particular vhost,
29 * - must receive and issue events inside the event loop
30 *
31 * lws_sequencer-s are bound to a pt (per-thread) which for the default case of
32 * one service thread is the same as binding to an lws_context.
33 */
34/*
35 * retry backoff table... retry n happens after .retry_ms_table[n] ms, with
36 * the last entry used if n is greater than the number of entries.
37 *
38 * The first .conceal_count retries are concealed, but after that the failures
39 * are reported.
40 */
41
42typedef enum {
43 LWSSEQ_CREATED, /* sequencer created */
44 LWSSEQ_DESTROYED, /* sequencer destroyed */
45 LWSSEQ_TIMED_OUT, /* sequencer timeout */
46 LWSSEQ_HEARTBEAT, /* 1Hz callback */
47
48 LWSSEQ_WSI_CONNECTED, /* wsi we bound to us has connected */
49 LWSSEQ_WSI_CONN_FAIL, /* wsi we bound to us has failed to connect */
50 LWSSEQ_WSI_CONN_CLOSE, /* wsi we bound to us has closed */
51
52
53 LWSSEQ_SS_STATE_BASE, /* secure streams owned by a sequencer provide
54 * automatic messages about state changes on
55 * the sequencer, passing the oridinal in the
56 * event argument field. The message index is
57 * LWSSEQ_SS_STATE_BASE + the enum from
58 * lws_ss_constate_t */
59
60 LWSSEQ_USER_BASE = 100 /* define your events from here */
61} lws_seq_events_t;
62
63typedef enum lws_seq_cb_return {
64 LWSSEQ_RET_CONTINUE,
65 LWSSEQ_RET_DESTROY
66} lws_seq_cb_return_t;
67
68/*
69 * handler for this sequencer. Return 0 if OK else nonzero to destroy the
70 * sequencer. LWSSEQ_DESTROYED will be called back to the handler so it can
71 * close / destroy any private assets associated with the sequence.
72 *
73 * The callback may return either LWSSEQ_RET_CONTINUE for the sequencer to
74 * resume or LWSSEQ_RET_DESTROY to indicate the sequence is finished.
75 *
76 * Event indexes consist of some generic ones but mainly user-defined ones
77 * starting from LWSSEQ_USER_BASE.
78 */
79typedef lws_seq_cb_return_t (*lws_seq_event_cb)(struct lws_sequencer *seq,
80 void *user, int event, void *data, void *aux);
81
82typedef struct lws_seq_info {
83 struct lws_context *context; /* lws_context for seq */
84 int tsi; /* thread service idx */
85 size_t user_size; /* size of user alloc */
86 void **puser; /* place ptr to user */
87 lws_seq_event_cb cb; /* seq callback */
88 const char *name; /* seq name */
89 const lws_retry_bo_t *retry; /* retry policy */
90 uint8_t wakesuspend:1; /* important enough to
91 * wake system */
92} lws_seq_info_t;
93
109LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
110lws_seq_create(lws_seq_info_t *info);
111
122LWS_VISIBLE LWS_EXTERN void
123lws_seq_destroy(struct lws_sequencer **seq);
124
142LWS_VISIBLE LWS_EXTERN int
143lws_seq_queue_event(struct lws_sequencer *seq, lws_seq_events_t e, void *data,
144 void *aux);
145
162LWS_VISIBLE LWS_EXTERN int
163lws_seq_check_wsi(struct lws_sequencer *seq, struct lws *wsi);
164
165#define LWSSEQTO_NONE 0
166
192LWS_VISIBLE LWS_EXTERN int
193lws_seq_timeout_us(struct lws_sequencer *seq, lws_usec_t us);
194
208LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
209lws_seq_from_user(void *u);
210
220LWS_VISIBLE LWS_EXTERN lws_usec_t
221lws_seq_us_since_creation(struct lws_sequencer *seq);
222
231LWS_VISIBLE LWS_EXTERN const char *
232lws_seq_name(struct lws_sequencer *seq);
233
242LWS_VISIBLE LWS_EXTERN struct lws_context *
243lws_seq_get_context(struct lws_sequencer *seq);
Definition lws-sequencer.h:82