lws-sequencer.h

 /*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 * lws_sequencer is intended to help implement sequences that:
 *
 *  - outlive a single connection lifetime,
 *  - are not associated with a particular protocol,
 *  - are not associated with a particular vhost,
 *  - must receive and issue events inside the event loop
 *
 * lws_sequencer-s are bound to a pt (per-thread) which for the default case of
 * one service thread is the same as binding to an lws_context.
 */
/*
 * retry backoff table... retry n happens after .retry_ms_table[n] ms, with
 * the last entry used if n is greater than the number of entries.
 *
 * The first .conceal_count retries are concealed, but after that the failures
 * are reported.
 */
 
typedef enum {
        LWSSEQ_CREATED,         /* sequencer created */
        LWSSEQ_DESTROYED,       /* sequencer destroyed */
        LWSSEQ_TIMED_OUT,       /* sequencer timeout */
        LWSSEQ_HEARTBEAT,       /* 1Hz callback */
 
        LWSSEQ_WSI_CONNECTED,   /* wsi we bound to us has connected */
        LWSSEQ_WSI_CONN_FAIL,   /* wsi we bound to us has failed to connect */
        LWSSEQ_WSI_CONN_CLOSE,  /* wsi we bound to us has closed */
 
 
        LWSSEQ_SS_STATE_BASE,   /* secure streams owned by a sequencer provide
                                 * automatic messages about state changes on
                                 * the sequencer, passing the oridinal in the
                                 * event argument field.  The message index is
                                 * LWSSEQ_SS_STATE_BASE + the enum from
                                 * lws_ss_constate_t */
 
        LWSSEQ_USER_BASE = 100  /* define your events from here */
} lws_seq_events_t;
 
typedef enum lws_seq_cb_return {
        LWSSEQ_RET_CONTINUE,
        LWSSEQ_RET_DESTROY
} lws_seq_cb_return_t;
 
/*
 * handler for this sequencer.  Return 0 if OK else nonzero to destroy the
 * sequencer.  LWSSEQ_DESTROYED will be called back to the handler so it can
 * close / destroy any private assets associated with the sequence.
 *
 * The callback may return either LWSSEQ_RET_CONTINUE for the sequencer to
 * resume or LWSSEQ_RET_DESTROY to indicate the sequence is finished.
 *
 * Event indexes consist of some generic ones but mainly user-defined ones
 * starting from LWSSEQ_USER_BASE.
 */
typedef lws_seq_cb_return_t (*lws_seq_event_cb)(struct lws_sequencer *seq,
                             void *user, int event, void *data, void *aux);
 
typedef struct lws_seq_info {
        struct lws_context              *context;   /* lws_context for seq */
        int                             tsi;        /* thread service idx */
        size_t                          user_size;  /* size of user alloc */
        void                            **puser;    /* place ptr to user */
        lws_seq_event_cb                cb;         /* seq callback */
        const char                      *name;      /* seq name */
        const lws_retry_bo_t            *retry;     /* retry policy */
        uint8_t                         wakesuspend:1; /* important enough to
                                                     * wake system */
} lws_seq_info_t;
 
LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
lws_seq_create(lws_seq_info_t *info);
 
LWS_VISIBLE LWS_EXTERN void
lws_seq_destroy(struct lws_sequencer **seq);
 
LWS_VISIBLE LWS_EXTERN int
lws_seq_queue_event(struct lws_sequencer *seq, lws_seq_events_t e, void *data,
                          void *aux);
 
LWS_VISIBLE LWS_EXTERN int
lws_seq_check_wsi(struct lws_sequencer *seq, struct lws *wsi);
 
#define LWSSEQTO_NONE 0
 
LWS_VISIBLE LWS_EXTERN int
lws_seq_timeout_us(struct lws_sequencer *seq, lws_usec_t us);
 
LWS_VISIBLE LWS_EXTERN struct lws_sequencer *
lws_seq_from_user(void *u);
 
LWS_VISIBLE LWS_EXTERN lws_usec_t
lws_seq_us_since_creation(struct lws_sequencer *seq);
 
LWS_VISIBLE LWS_EXTERN const char *
lws_seq_name(struct lws_sequencer *seq);
 
LWS_VISIBLE LWS_EXTERN struct lws_context *
lws_seq_get_context(struct lws_sequencer *seq);