libwebsockets
Lightweight C library for HTML5 websockets
Built-in service loop entry

Macros

#define lws_plat_service_tsi   lws_service_tsi
 

Functions

LWS_VISIBLE LWS_EXTERN int lws_service (struct lws_context *context, int timeout_ms)
 
LWS_VISIBLE LWS_EXTERN int lws_service_tsi (struct lws_context *context, int timeout_ms, int tsi)
 
LWS_VISIBLE LWS_EXTERN void lws_cancel_service_pt (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void lws_cancel_service (struct lws_context *context)
 
LWS_VISIBLE LWS_EXTERN int lws_service_fd (struct lws_context *context, struct lws_pollfd *pollfd)
 
LWS_VISIBLE LWS_EXTERN int lws_service_fd_tsi (struct lws_context *context, struct lws_pollfd *pollfd, int tsi)
 
LWS_VISIBLE LWS_EXTERN int lws_service_adjust_timeout (struct lws_context *context, int timeout_ms, int tsi)
 
LWS_VISIBLE LWS_EXTERN int lws_handle_POLLOUT_event (struct lws *wsi, struct lws_pollfd *pollfd)
 

Detailed Description

Built-in service loop entry

If you're not using libev / libuv, these apis are needed to enter the poll() wait in lws and service any connections with pending events.

Function Documentation

◆ lws_cancel_service()

LWS_VISIBLE LWS_EXTERN void lws_cancel_service ( struct lws_context *  context)

#include <include/libwebsockets/lws-service.h>

lws_cancel_service() - Cancel wait for new pending socket activity

Parameters
contextWebsocket context

This function creates an immediate "synchronous interrupt" to the lws poll() wait or event loop. As soon as possible in the serialzed service sequencing, a LWS_CALLBACK_EVENT_WAIT_CANCELLED callback is sent to every protocol on every vhost.

lws_cancel_service() may be called from another thread while the context exists, and its effect will be immediately serialized.

◆ lws_cancel_service_pt()

LWS_VISIBLE LWS_EXTERN void lws_cancel_service_pt ( struct lws *  wsi)

#include <include/libwebsockets/lws-service.h>

lws_cancel_service_pt() - Cancel servicing of pending socket activity on one thread

Parameters
wsiCancel service on the thread this wsi is serviced by

Same as lws_cancel_service(), but targets a single service thread, the one the wsi belongs to. You probably want to use lws_cancel_service() instead.

◆ lws_service()

LWS_VISIBLE LWS_EXTERN int lws_service ( struct lws_context *  context,
int  timeout_ms 
)

#include <include/libwebsockets/lws-service.h>

lws_service() - Service any pending websocket activity

Parameters
contextWebsocket context
timeout_msSet to 0; ignored; for backward compatibility
 This function deals with any pending websocket traffic, for three
 kinds of event.  It handles these events on both server and client
 types of connection the same.

 1) Accept new connections to our context's server

 2) Call the receive callback for incoming frame data received by
     server or client connections.
Since v3.2 internally the timeout wait is ignored, the lws scheduler is smart enough to stay asleep until an event is queued.

◆ lws_service_adjust_timeout()

LWS_VISIBLE LWS_EXTERN int lws_service_adjust_timeout ( struct lws_context *  context,
int  timeout_ms,
int  tsi 
)

#include <include/libwebsockets/lws-service.h>

lws_service_adjust_timeout() - Check for any connection needing forced service

Parameters
contextWebsocket context
timeout_msThe original poll timeout value. You can just set this to 1 if you don't really have a poll timeout.
tsithread service index

Under some conditions connections may need service even though there is no pending network action on them, this is "forced service". For default poll() and libuv / libev, the library takes care of calling this and dealing with it for you. But for external poll() integration, you need access to the apis.

If anybody needs "forced service", returned timeout is zero. In that case, you can call lws_service_tsi() with a timeout of -1 to only service guys who need forced service.

◆ lws_service_fd()

LWS_VISIBLE LWS_EXTERN int lws_service_fd ( struct lws_context *  context,
struct lws_pollfd *  pollfd 
)

#include <include/libwebsockets/lws-service.h>

lws_service_fd() - Service polled socket with something waiting

Parameters
contextWebsocket context
pollfdThe pollfd entry describing the socket fd and which events happened

This function takes a pollfd that has POLLIN or POLLOUT activity and services it according to the state of the associated struct lws.

The one call deals with all "service" that might happen on a socket including listen accepts, http files as well as websocket protocol.

If a pollfd says it has something, you can just pass it to lws_service_fd() whether it is a socket handled by lws or not. If it sees it is a lws socket, the traffic will be handled and pollfd->revents will be zeroed now.

If the socket is foreign to lws, it leaves revents alone. So you can see if you should service yourself by checking the pollfd revents after letting lws try to service it.

lws before v3.2 allowed pollfd to be NULL, to indicate that background periodic processing should be done. Since v3.2, lws schedules any items that need handling in the future using lws_sul and NULL is no longer valid.

◆ lws_service_fd_tsi()

LWS_VISIBLE LWS_EXTERN int lws_service_fd_tsi ( struct lws_context *  context,
struct lws_pollfd *  pollfd,
int  tsi 
)

#include <include/libwebsockets/lws-service.h>

lws_service_fd_tsi() - Service polled socket in specific service thread

Parameters
contextWebsocket context
pollfdThe pollfd entry describing the socket fd and which events happened.
tsithread service index

Same as lws_service_fd() but used with multiple service threads

◆ lws_service_tsi()

LWS_VISIBLE LWS_EXTERN int lws_service_tsi ( struct lws_context *  context,
int  timeout_ms,
int  tsi 
)

#include <include/libwebsockets/lws-service.h>

lws_service_tsi() - Service any pending websocket activity

Parameters
contextWebsocket context
timeout_msSet to 0; ignored; for backwards compatibility
tsiThread service index, starting at 0

Same as lws_service(), but for a specific thread service index. Only needed if you are spawning multiple service threads that operate on the same lws_context.