lws-timeout-timer.h

Go to the documentation of this file.

/*
 * 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.
 */
 
/*! \defgroup timeout Connection timeouts
 
    APIs related to setting connection timeouts
*/
//@{
 
#if defined(STANDALONE)
struct lws_context_standalone;
#define lws_context lws_context_standalone
#endif
 
/*
 * NOTE: These public enums are part of the abi.  If you want to add one,
 * add it at where specified so existing users are unaffected.
 */
enum pending_timeout {
        NO_PENDING_TIMEOUT                                      =  0,
        PENDING_TIMEOUT_AWAITING_PROXY_RESPONSE                 =  1,
        PENDING_TIMEOUT_AWAITING_CONNECT_RESPONSE               =  2,
        PENDING_TIMEOUT_ESTABLISH_WITH_SERVER                   =  3,
        PENDING_TIMEOUT_AWAITING_SERVER_RESPONSE                =  4,
        PENDING_TIMEOUT_AWAITING_PING                           =  5,
        PENDING_TIMEOUT_CLOSE_ACK                               =  6,
        PENDING_TIMEOUT_UNUSED1                                 =  7,
        PENDING_TIMEOUT_SENT_CLIENT_HANDSHAKE                   =  8,
        PENDING_TIMEOUT_SSL_ACCEPT                              =  9,
        PENDING_TIMEOUT_HTTP_CONTENT                            = 10,
        PENDING_TIMEOUT_AWAITING_CLIENT_HS_SEND                 = 11,
        PENDING_FLUSH_STORED_SEND_BEFORE_CLOSE                  = 12,
        PENDING_TIMEOUT_SHUTDOWN_FLUSH                          = 13,
        PENDING_TIMEOUT_CGI                                     = 14,
        PENDING_TIMEOUT_HTTP_KEEPALIVE_IDLE                     = 15,
        PENDING_TIMEOUT_WS_PONG_CHECK_SEND_PING                 = 16,
        PENDING_TIMEOUT_WS_PONG_CHECK_GET_PONG                  = 17,
        PENDING_TIMEOUT_CLIENT_ISSUE_PAYLOAD                    = 18,
        PENDING_TIMEOUT_AWAITING_SOCKS_GREETING_REPLY           = 19,
        PENDING_TIMEOUT_AWAITING_SOCKS_CONNECT_REPLY            = 20,
        PENDING_TIMEOUT_AWAITING_SOCKS_AUTH_REPLY               = 21,
        PENDING_TIMEOUT_KILLED_BY_SSL_INFO                      = 22,
        PENDING_TIMEOUT_KILLED_BY_PARENT                        = 23,
        PENDING_TIMEOUT_CLOSE_SEND                              = 24,
        PENDING_TIMEOUT_HOLDING_AH                              = 25,
        PENDING_TIMEOUT_UDP_IDLE                                = 26,
        PENDING_TIMEOUT_CLIENT_CONN_IDLE                        = 27,
        PENDING_TIMEOUT_LAGGING                                 = 28,
        PENDING_TIMEOUT_THREADPOOL                              = 29,
        PENDING_TIMEOUT_THREADPOOL_TASK                         = 30,
        PENDING_TIMEOUT_KILLED_BY_PROXY_CLIENT_CLOSE            = 31,
        PENDING_TIMEOUT_USER_OK                                 = 32,
 
        /****** add new things just above ---^ ******/
 
        PENDING_TIMEOUT_USER_REASON_BASE                        = 1000
};
 
#define lws_time_in_microseconds lws_now_usecs
 
#define LWS_TO_KILL_ASYNC -1
/**< If LWS_TO_KILL_ASYNC is given as the timeout sec in a lws_set_timeout()
 * call, then the connection is marked to be killed at the next timeout
 * check.  This is how you should force-close the wsi being serviced if
 * you are doing it outside the callback (where you should close by nonzero
 * return).
 */
#define LWS_TO_KILL_SYNC -2
/**< If LWS_TO_KILL_SYNC is given as the timeout sec in a lws_set_timeout()
 * call, then the connection is closed before returning (which may delete
 * the wsi).  This should only be used where the wsi being closed is not the
 * wsi currently being serviced.
 */
/**
 * lws_set_timeout() - marks the wsi as subject to a timeout some seconds hence
 *
 * \param wsi:  Websocket connection instance
 * \param reason:       timeout reason
 * \param secs: how many seconds.  You may set to LWS_TO_KILL_ASYNC to
 *              force the connection to timeout at the next opportunity, or
 *              LWS_TO_KILL_SYNC to close it synchronously if you know the
 *              wsi is not the one currently being serviced.
 */
LWS_VISIBLE LWS_EXTERN void
lws_set_timeout(struct lws *wsi, enum pending_timeout reason, int secs);
 
/**
 * lws_set_timeout_us() - marks the wsi as subject to a timeout some us hence
 *
 * \param wsi:  Websocket connection instance
 * \param reason:       timeout reason
 * \param us:   0 removes the timeout, otherwise number of us to wait
 *
 * Higher-resolution version of lws_set_timeout().  Actual resolution depends
 * on platform and load, usually ms.
 */
void
lws_set_timeout_us(struct lws *wsi, enum pending_timeout reason, lws_usec_t us);
 
/* helper for clearer LWS_TO_KILL_ASYNC / LWS_TO_KILL_SYNC usage */
#define lws_wsi_close(w, to_kill) lws_set_timeout(w, 1, to_kill)
 
 
#define LWS_SET_TIMER_USEC_CANCEL ((lws_usec_t)-1ll)
#define LWS_USEC_PER_SEC ((lws_usec_t)1000000)
 
/**
 * lws_set_timer_usecs() - schedules a callback on the wsi in the future
 *
 * \param wsi:  Websocket connection instance
 * \param usecs:  LWS_SET_TIMER_USEC_CANCEL removes any existing scheduled
 *                callback, otherwise number of microseconds in the future
 *                the callback will occur at.
 *
 * NOTE: event loop support for this:
 *
 *  default poll() loop:   yes
 *  libuv event loop:      yes
 *  libev:    not implemented (patch welcome)
 *  libevent: not implemented (patch welcome)
 *
 * After the deadline expires, the wsi will get a callback of type
 * LWS_CALLBACK_TIMER and the timer is exhausted.  The deadline may be
 * continuously deferred by further calls to lws_set_timer_usecs() with a later
 * deadline, or cancelled by lws_set_timer_usecs(wsi, -1).
 *
 * If the timer should repeat, lws_set_timer_usecs() must be called again from
 * LWS_CALLBACK_TIMER.
 *
 * Accuracy depends on the platform and the load on the event loop or system...
 * all that's guaranteed is the callback will come after the requested wait
 * period.
 */
LWS_VISIBLE LWS_EXTERN void
lws_set_timer_usecs(struct lws *wsi, lws_usec_t usecs);
 
struct lws_sorted_usec_list;
 
typedef void (*sul_cb_t)(struct lws_sorted_usec_list *sul);
 
typedef struct lws_sorted_usec_list {
        struct lws_dll2 list;   /* simplify the code by keeping this at start */
        lws_usec_t      us;
        sul_cb_t        cb;
        uint32_t        latency_us;     /* us it may safely be delayed */
} lws_sorted_usec_list_t;
 
/*
 * There are multiple sul owners to allow accounting for, a) events that must
 * wake from suspend, and b) events that can be missued due to suspend
 */
#define LWS_COUNT_PT_SUL_OWNERS                 2
 
#define LWSSULLI_MISS_IF_SUSPENDED              0
#define LWSSULLI_WAKE_IF_SUSPENDED              1
 
/*
 * lws_sul2_schedule() - schedule a callback
 *
 * \param context: the lws_context
 * \param tsi: the thread service index (usually 0)
 * \param flags: LWSSULLI_...
 * \param sul: pointer to the sul element
 *
 * Generic callback-at-a-later time function.  The callback happens on the
 * event loop thread context.
 *
 * Although the api has us resultion, the actual resolution depends on the
 * platform and may be, eg, 1ms.
 *
 * This doesn't allocate and doesn't fail.
 *
 * If flags contains LWSSULLI_WAKE_IF_SUSPENDED, the scheduled event is placed
 * on a sul owner list that, if the system has entered low power suspend mode,
 * tries to arrange that the system should wake from platform suspend just
 * before the event is due.  Scheduled events without this flag will be missed
 * in the case the system is in suspend and nothing else happens to have woken
 * it.
 *
 * You can call it again with another us value to change the delay or move the
 * event to a different owner (ie, wake or miss on suspend).
 */
LWS_VISIBLE LWS_EXTERN void
lws_sul2_schedule(struct lws_context *context, int tsi, int flags,
                  lws_sorted_usec_list_t *sul);
 
/*
 * lws_sul_cancel() - cancel scheduled callback
 *
 * \param sul: pointer to the sul element
 *
 * If it's scheduled, remove the sul from its owning sorted list.
 * If not scheduled, it's a NOP.
 */
LWS_VISIBLE LWS_EXTERN void
lws_sul_cancel(lws_sorted_usec_list_t *sul);
 
/*
 * lws_sul_earliest_wakeable_event() - get earliest wake-from-suspend event
 *
 * \param ctx: the lws context
 * \param pearliest: pointer to lws_usec_t to take the result
 *
 * Either returns 1 if no pending event, or 0 and sets *pearliest to the
 * MONOTONIC time of the current earliest next expected event.
 */
LWS_VISIBLE LWS_EXTERN int
lws_sul_earliest_wakeable_event(struct lws_context *ctx, lws_usec_t *pearliest);
 
/*
 * For backwards compatibility
 *
 * If us is LWS_SET_TIMER_USEC_CANCEL, the sul is removed from the scheduler.
 * New code can use lws_sul_cancel()
 */
 
LWS_VISIBLE LWS_EXTERN void
lws_sul_schedule(struct lws_context *ctx, int tsi, lws_sorted_usec_list_t *sul,
                 sul_cb_t _cb, lws_usec_t _us);
LWS_VISIBLE LWS_EXTERN void
lws_sul_schedule_wakesuspend(struct lws_context *ctx, int tsi,
                             lws_sorted_usec_list_t *sul, sul_cb_t _cb,
                             lws_usec_t _us);
 
#if defined(LWS_WITH_SUL_DEBUGGING)
/**
 * lws_sul_debug_zombies() - assert there are no scheduled sul in a given object
 *
 * \param ctx: lws_context
 * \param po: pointer to the object that is about to be destroyed
 * \param len: length of the object that is about to be destroyed
 * \param destroy_description: string clue what any failure is related to
 *
 * This is an optional debugging helper that walks the sul scheduler lists
 * confirming that there are no suls scheduled that live inside the object
 * footprint described by po and len.  When internal objects are about to be
 * destroyed, like wsi / user_data or secure stream handles, if
 * LWS_WITH_SUL_DEBUGGING is enabled the scheduler is checked for anything
 * in the object being destroyed.  If something found, an error is printed and
 * an assert fired.
 *
 * Internal sul like timeouts should always be cleaned up correctly, but user
 * suls in, eg, wsi user_data area, or in secure stream user allocation, may be
 * the cause of difficult to find bugs if valgrind not available and the user
 * code left a sul in the scheduler after destroying the object the sul was
 * living in.
 */
LWS_VISIBLE LWS_EXTERN void
lws_sul_debug_zombies(struct lws_context *ctx, void *po, size_t len,
                      const char *destroy_description);
#else
#define lws_sul_debug_zombies(_a, _b, _c, _d)
#endif
 
/*
 * lws_validity_confirmed() - reset the validity timer for a network connection
 *
 * \param wsi: the connection that saw traffic proving the connection valid
 *
 * Network connections are subject to intervals defined by the context, the
 * vhost if server connections, or the client connect info if a client
 * connection.  If the connection goes longer than the specified time since
 * last observing traffic that can only happen if traffic is passing in both
 * directions, then lws will try to create a PING transaction on the network
 * connection.
 *
 * If the connection reaches the specified `.secs_since_valid_hangup` time
 * still without any proof of validity, the connection will be closed.
 *
 * If the PONG comes, or user code observes traffic that satisfies the proof
 * that both directions are passing traffic to the peer and calls this api,
 * the connection validity timer is reset and the scheme repeats.
 */
LWS_VISIBLE LWS_EXTERN void
lws_validity_confirmed(struct lws *wsi);
 
/*
 * These are not normally needed, they're exported for the case there's code
 * using lws_sul for which lws is an optional link dependency.
 */
 
LWS_VISIBLE LWS_EXTERN int
__lws_sul_insert(lws_dll2_owner_t *own, lws_sorted_usec_list_t *sul);
 
LWS_VISIBLE LWS_EXTERN lws_usec_t
__lws_sul_service_ripe(lws_dll2_owner_t *own, int own_len, lws_usec_t usnow);
 
#if defined(STANDALONE)
#undef lws_context
#endif
 
///@}