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
25/** \defgroup service Built-in service loop entry
26 *
27 * ##Built-in service loop entry
28 *
29 * If you're not using libev / libuv, these apis are needed to enter the poll()
30 * wait in lws and service any connections with pending events.
31 */
32///@{
33
34/**
35 * lws_service() - Service any pending websocket activity
36 * \param context: Websocket context
37 * \param timeout_ms: Set to 0; ignored; for backward compatibility
38 *
39 * This function deals with any pending websocket traffic, for three
40 * kinds of event. It handles these events on both server and client
41 * types of connection the same.
42 *
43 * 1) Accept new connections to our context's server
44 *
45 * 2) Call the receive callback for incoming frame data received by
46 * server or client connections.
47 *
48 * Since v3.2 internally the timeout wait is ignored, the lws scheduler is
49 * smart enough to stay asleep until an event is queued.
50 */
51LWS_VISIBLE LWS_EXTERN int
52lws_service(struct lws_context *context, int timeout_ms);
53
54/**
55 * lws_service_tsi() - Service any pending websocket activity
56 *
57 * \param context: Websocket context
58 * \param timeout_ms: Set to 0; ignored; for backwards compatibility
59 * \param tsi: Thread service index, starting at 0
60 *
61 * Same as lws_service(), but for a specific thread service index. Only needed
62 * if you are spawning multiple service threads that operate on the same lws_context.
63 */
64LWS_VISIBLE LWS_EXTERN int
65lws_service_tsi(struct lws_context *context, int timeout_ms, int tsi);
66
67/**
68 * lws_cancel_service_pt() - Cancel servicing of pending socket activity
69 * on one thread
70 * \param wsi: Cancel service on the thread this wsi is serviced by
71 *
72 * Same as lws_cancel_service(), but targets a single service thread, the one
73 * the wsi belongs to. You probably want to use lws_cancel_service() instead.
74 */
75LWS_VISIBLE LWS_EXTERN void
76lws_cancel_service_pt(struct lws *wsi);
77
78/**
79 * lws_cancel_service() - Cancel wait for new pending socket activity
80 * \param context: Websocket context
81 *
82 * This function creates an immediate "synchronous interrupt" to the lws poll()
83 * wait or event loop. As soon as possible in the serialzed service sequencing,
84 * a LWS_CALLBACK_EVENT_WAIT_CANCELLED callback is sent to every protocol on
85 * every vhost.
86 *
87 * lws_cancel_service() may be called from another thread while the context
88 * exists, and its effect will be immediately serialized.
89 */
90LWS_VISIBLE LWS_EXTERN void
91lws_cancel_service(struct lws_context *context);
92
93/**
94 * lws_service_fd() - Service polled socket with something waiting
95 * \param context: Websocket context
96 * \param pollfd: The pollfd entry describing the socket fd and which events
97 * happened
98 *
99 * This function takes a pollfd that has POLLIN or POLLOUT activity and
100 * services it according to the state of the associated
101 * struct lws.
102 *
103 * The one call deals with all "service" that might happen on a socket
104 * including listen accepts, http files as well as websocket protocol.
105 *
106 * If a pollfd says it has something, you can just pass it to
107 * lws_service_fd() whether it is a socket handled by lws or not.
108 * If it sees it is a lws socket, the traffic will be handled and
109 * pollfd->revents will be zeroed now.
110 *
111 * If the socket is foreign to lws, it leaves revents alone. So you can
112 * see if you should service yourself by checking the pollfd revents
113 * after letting lws try to service it.
114 *
115 * lws before v3.2 allowed pollfd to be NULL, to indicate that background
116 * periodic processing should be done. Since v3.2, lws schedules any items
117 * that need handling in the future using lws_sul and NULL is no longer valid.
118 */
119LWS_VISIBLE LWS_EXTERN int
120lws_service_fd(struct lws_context *context, struct lws_pollfd *pollfd);
121
122/**
123 * lws_service_fd_tsi() - Service polled socket in specific service thread
124 * \param context: Websocket context
125 * \param pollfd: The pollfd entry describing the socket fd and which events
126 * happened.
127 * \param tsi: thread service index
128 *
129 * Same as lws_service_fd() but used with multiple service threads
130 */
131LWS_VISIBLE LWS_EXTERN int
132lws_service_fd_tsi(struct lws_context *context, struct lws_pollfd *pollfd,
133 int tsi);
134
135/**
136 * lws_service_adjust_timeout() - Check for any connection needing forced service
137 * \param context: Websocket context
138 * \param timeout_ms: The original poll timeout value. You can just set this
139 * to 1 if you don't really have a poll timeout.
140 * \param tsi: thread service index
141 *
142 * Under some conditions connections may need service even though there is no
143 * pending network action on them, this is "forced service". For default
144 * poll() and libuv / libev, the library takes care of calling this and
145 * dealing with it for you. But for external poll() integration, you need
146 * access to the apis.
147 *
148 * If anybody needs "forced service", returned timeout is zero. In that case,
149 * you can call lws_service_tsi() with a timeout of -1 to only service
150 * guys who need forced service.
151 */
152LWS_VISIBLE LWS_EXTERN int
153lws_service_adjust_timeout(struct lws_context *context, int timeout_ms, int tsi);
154
155/* Backwards compatibility */
156#define lws_plat_service_tsi lws_service_tsi
157
158LWS_VISIBLE LWS_EXTERN int
159lws_handle_POLLOUT_event(struct lws *wsi, struct lws_pollfd *pollfd);
160
161///@}
162
163/*! \defgroup uv libuv helpers
164 *
165 * ##libuv helpers
166 *
167 * APIs specific to libuv event loop itegration
168 */
169///@{
170#if defined(LWS_WITH_LIBUV) && defined(UV_ERRNO_MAP)
171
172/*
173 * Any direct libuv allocations in lws protocol handlers must participate in the
174 * lws reference counting scheme. Two apis are provided:
175 *
176 * - lws_libuv_static_refcount_add(handle, context, tsi) to mark the handle with
177 * a pointer to the context and increment the global uv object counter
178 *
179 * - lws_libuv_static_refcount_del() which should be used as the close callback
180 * for your own libuv objects declared in the protocol scope.
181 *
182 * Using the apis allows lws to detach itself from a libuv loop completely
183 * cleanly and at the moment all of its libuv objects have completed close.
184 */
185
186LWS_VISIBLE LWS_EXTERN uv_loop_t *
187lws_uv_getloop(struct lws_context *context, int tsi);
188
189LWS_VISIBLE LWS_EXTERN void
190lws_libuv_static_refcount_add(uv_handle_t *, struct lws_context *context,
191 int tsi);
192
193LWS_VISIBLE LWS_EXTERN void
194lws_libuv_static_refcount_del(uv_handle_t *);
195
196#endif /* LWS_WITH_LIBUV */
197
198#if defined(LWS_PLAT_FREERTOS)
199#define lws_libuv_static_refcount_add(_a, _b, _c)
200#define lws_libuv_static_refcount_del NULL
201#endif
202///@}
203