lib/service.c

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   3  *
   4  * Copyright (C) 2010-2015 Andy Green <andy@warmcat.com>
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation:
   9  *  version 2.1 of the License.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19  *  MA  02110-1301  USA
  20  */
  21
  22 #include "private-libwebsockets.h"
  23
  24 static int
  25 lws_calllback_as_writeable(struct libwebsocket_context *context,
  26                    struct libwebsocket *wsi)
  27 {
  28         int n;
  29
  30         switch (wsi->mode) {
  31         case LWS_CONNMODE_WS_CLIENT:
  32                 n = LWS_CALLBACK_CLIENT_WRITEABLE;
  33                 break;
  34         case LWS_CONNMODE_WS_SERVING:
  35                 n = LWS_CALLBACK_SERVER_WRITEABLE;
  36                 break;
  37         default:
  38                 n = LWS_CALLBACK_HTTP_WRITEABLE;
  39                 break;
  40         }
  41         lwsl_info("%s: %p (user=%p)\n", __func__, wsi, wsi->user_space);
  42         return user_callback_handle_rxflow(wsi->protocol->callback, context,
  43                         wsi, (enum libwebsocket_callback_reasons) n,
  44                                                       wsi->user_space, NULL, 0);
  45 }
  46
  47 int
  48 lws_handle_POLLOUT_event(struct libwebsocket_context *context,
  49                    struct libwebsocket *wsi, struct libwebsocket_pollfd *pollfd)
  50 {
  51         int n;
  52         struct lws_tokens eff_buf;
  53 #ifdef LWS_USE_HTTP2
  54         struct libwebsocket *wsi2;
  55 #endif
  56         int ret;
  57         int m;
  58         int write_type = LWS_WRITE_PONG;
  59
  60         /* pending truncated sends have uber priority */
  61
  62         if (wsi->truncated_send_len) {
  63                 if (lws_issue_raw(wsi, wsi->truncated_send_malloc +
  64                                 wsi->truncated_send_offset,
  65                                                 wsi->truncated_send_len) < 0) {
  66                         lwsl_info("lws_handle_POLLOUT_event signalling to close\n");
  67                         return -1;
  68                 }
  69                 /* leave POLLOUT active either way */
  70                 return 0;
  71         } else
  72                 if (wsi->state == WSI_STATE_FLUSHING_STORED_SEND_BEFORE_CLOSE) {
  73                         lwsl_info("***** %x signalling to close in POLLOUT handler\n", wsi);
  74                         return -1; /* retry closing now */
  75                 }
  76 #ifdef LWS_USE_HTTP2
  77         /* protocol packets are next */
  78         if (wsi->pps) {
  79                 lwsl_info("servicing pps %d\n", wsi->pps);
  80                 switch (wsi->pps) {
  81                 case LWS_PPS_HTTP2_MY_SETTINGS:
  82                 case LWS_PPS_HTTP2_ACK_SETTINGS:
  83                         lws_http2_do_pps_send(context, wsi);
  84                         break;
  85                 default:
  86                         break;
  87                 }
  88                 wsi->pps = LWS_PPS_NONE;
  89                 libwebsocket_rx_flow_control(wsi, 1);
  90
  91                 return 0; /* leave POLLOUT active */
  92         }
  93 #endif
  94         /* pending control packets have next priority */
  95
  96         if ((wsi->state == WSI_STATE_ESTABLISHED &&
  97              wsi->u.ws.ping_pending_flag) ||
  98             (wsi->state == WSI_STATE_RETURNED_CLOSE_ALREADY &&
  99              wsi->u.ws.payload_is_close)) {
 100
 101                 if (wsi->u.ws.payload_is_close)
 102                         write_type = LWS_WRITE_CLOSE;
 103
 104                 n = libwebsocket_write(wsi,
 105                                 &wsi->u.ws.ping_payload_buf[
 106                                         LWS_SEND_BUFFER_PRE_PADDING],
 107                                         wsi->u.ws.ping_payload_len,
 108                                                                write_type);
 109                 if (n < 0)
 110                         return -1;
 111
 112                 /* well he is sent, mark him done */
 113                 wsi->u.ws.ping_pending_flag = 0;
 114                 if (wsi->u.ws.payload_is_close)
 115                         /* oh... a close frame was it... then we are done */
 116                         return -1;
 117
 118                 /* otherwise for PING, leave POLLOUT active either way */
 119                 return 0;
 120         }
 121
 122         /* if we are closing, don't confuse the user with writeable cb */
 123
 124         if (wsi->state == WSI_STATE_RETURNED_CLOSE_ALREADY)
 125                 goto user_service;
 126
 127         /* if nothing critical, user can get the callback */
 128
 129         m = lws_ext_callback_for_each_active(wsi, LWS_EXT_CALLBACK_IS_WRITEABLE,
 130                                                                        NULL, 0);
 131 #ifndef LWS_NO_EXTENSIONS
 132         if (!wsi->extension_data_pending)
 133                 goto user_service;
 134 #endif
 135         /*
 136          * check in on the active extensions, see if they
 137          * had pending stuff to spill... they need to get the
 138          * first look-in otherwise sequence will be disordered
 139          *
 140          * NULL, zero-length eff_buf means just spill pending
 141          */
 142
 143         ret = 1;
 144         while (ret == 1) {
 145
 146                 /* default to nobody has more to spill */
 147
 148                 ret = 0;
 149                 eff_buf.token = NULL;
 150                 eff_buf.token_len = 0;
 151
 152                 /* give every extension a chance to spill */
 153
 154                 m = lws_ext_callback_for_each_active(wsi,
 155                                         LWS_EXT_CALLBACK_PACKET_TX_PRESEND,
 156                                                                    &eff_buf, 0);
 157                 if (m < 0) {
 158                         lwsl_err("ext reports fatal error\n");
 159                         return -1;
 160                 }
 161                 if (m)
 162                         /*
 163                          * at least one extension told us he has more
 164                          * to spill, so we will go around again after
 165                          */
 166                         ret = 1;
 167
 168                 /* assuming they gave us something to send, send it */
 169
 170                 if (eff_buf.token_len) {
 171                         n = lws_issue_raw(wsi, (unsigned char *)eff_buf.token,
 172                                                              eff_buf.token_len);
 173                         if (n < 0) {
 174                                 lwsl_info("closing from POLLOUT spill\n");
 175                                 return -1;
 176                         }
 177                         /*
 178                          * Keep amount spilled small to minimize chance of this
 179                          */
 180                         if (n != eff_buf.token_len) {
 181                                 lwsl_err("Unable to spill ext %d vs %s\n",
 182                                                           eff_buf.token_len, n);
 183                                 return -1;
 184                         }
 185                 } else
 186                         continue;
 187
 188                 /* no extension has more to spill */
 189
 190                 if (!ret)
 191                         continue;
 192
 193                 /*
 194                  * There's more to spill from an extension, but we just sent
 195                  * something... did that leave the pipe choked?
 196                  */
 197
 198                 if (!lws_send_pipe_choked(wsi))
 199                         /* no we could add more */
 200                         continue;
 201
 202                 lwsl_info("choked in POLLOUT service\n");
 203
 204                 /*
 205                  * Yes, he's choked.  Leave the POLLOUT masked on so we will
 206                  * come back here when he is unchoked.  Don't call the user
 207                  * callback to enforce ordering of spilling, he'll get called
 208                  * when we come back here and there's nothing more to spill.
 209                  */
 210
 211                 return 0;
 212         }
 213 #ifndef LWS_NO_EXTENSIONS
 214         wsi->extension_data_pending = 0;
 215 #endif
 216 user_service:
 217         /* one shot */
 218
 219         if (pollfd) {
 220                 if (lws_change_pollfd(wsi, LWS_POLLOUT, 0)) {
 221                         lwsl_info("failled at set pollfd\n");
 222                         return 1;
 223                 }
 224
 225                 lws_libev_io(context, wsi, LWS_EV_STOP | LWS_EV_WRITE);
 226         }
 227
 228 #ifdef LWS_USE_HTTP2
 229         /*
 230          * we are the 'network wsi' for potentially many muxed child wsi with
 231          * no network connection of their own, who have to use us for all their
 232          * network actions.  So we use a round-robin scheme to share out the
 233          * POLLOUT notifications to our children.
 234          *
 235          * But because any child could exhaust the socket's ability to take
 236          * writes, we can only let one child get notified each time.
 237          *
 238          * In addition children may be closed / deleted / added between POLLOUT
 239          * notifications, so we can't hold pointers
 240          */
 241
 242         if (wsi->mode != LWS_CONNMODE_HTTP2_SERVING) {
 243                 lwsl_info("%s: non http2\n", __func__);
 244                 goto notify;
 245         }
 246
 247         wsi->u.http2.requested_POLLOUT = 0;
 248         if (!wsi->u.http2.initialized) {
 249                 lwsl_info("pollout on uninitialized http2 conn\n");
 250                 return 0;
 251         }
 252
 253         lwsl_info("%s: doing children\n", __func__);
 254
 255         wsi2 = wsi;
 256         do {
 257                 wsi2 = wsi2->u.http2.next_child_wsi;
 258                 lwsl_info("%s: child %p\n", __func__, wsi2);
 259                 if (!wsi2)
 260                         continue;
 261                 if (!wsi2->u.http2.requested_POLLOUT)
 262                         continue;
 263                 wsi2->u.http2.requested_POLLOUT = 0;
 264                 if (lws_calllback_as_writeable(context, wsi2)) {
 265                         lwsl_debug("Closing POLLOUT child\n");
 266                         libwebsocket_close_and_free_session(context, wsi2,
 267                                                 LWS_CLOSE_STATUS_NOSTATUS);
 268                 }
 269                 wsi2 = wsi;
 270         } while (wsi2 != NULL && !lws_send_pipe_choked(wsi));
 271
 272         lwsl_info("%s: completed\n", __func__);
 273
 274         return 0;
 275 notify:
 276 #endif
 277         return lws_calllback_as_writeable(context, wsi);
 278 }
 279
 280
 281
 282 int
 283 libwebsocket_service_timeout_check(struct libwebsocket_context *context,
 284                                      struct libwebsocket *wsi, unsigned int sec)
 285 {
 286         /*
 287          * if extensions want in on it (eg, we are a mux parent)
 288          * give them a chance to service child timeouts
 289          */
 290         if (lws_ext_callback_for_each_active(wsi, LWS_EXT_CALLBACK_1HZ, NULL, sec) < 0)
 291                 return 0;
 292
 293         if (!wsi->pending_timeout)
 294                 return 0;
 295
 296         /*
 297          * if we went beyond the allowed time, kill the
 298          * connection
 299          */
 300         if ((time_t)sec > wsi->pending_timeout_limit) {
 301                 lwsl_info("wsi %p: TIMEDOUT WAITING on %d\n", (void *)wsi, wsi->pending_timeout);
 302                 /*
 303                  * Since he failed a timeout, he already had a chance to do
 304                  * something and was unable to... that includes situations like
 305                  * half closed connections.  So process this "failed timeout"
 306                  * close as a violent death and don't try to do protocol
 307                  * cleanup like flush partials.
 308                  */
 309                 wsi->socket_is_permanently_unusable = 1;
 310                 libwebsocket_close_and_free_session(context,
 311                                                 wsi, LWS_CLOSE_STATUS_NOSTATUS);
 312                 return 1;
 313         }
 314
 315         return 0;
 316 }
 317
 318 int lws_rxflow_cache(struct libwebsocket *wsi, unsigned char *buf, int n, int len)
 319 {
 320         /* his RX is flowcontrolled, don't send remaining now */
 321         if (wsi->rxflow_buffer) {
 322                 /* rxflow while we were spilling prev rxflow */
 323                 lwsl_info("stalling in existing rxflow buf\n");
 324                 return 1;
 325         }
 326
 327         /* a new rxflow, buffer it and warn caller */
 328         lwsl_info("new rxflow input buffer len %d\n", len - n);
 329         wsi->rxflow_buffer = lws_malloc(len - n);
 330         wsi->rxflow_len = len - n;
 331         wsi->rxflow_pos = 0;
 332         memcpy(wsi->rxflow_buffer, buf + n, len - n);
 333
 334         return 0;
 335 }
 336
 337 /**
 338  * libwebsocket_service_fd() - Service polled socket with something waiting
 339  * @context:    Websocket context
 340  * @pollfd:     The pollfd entry describing the socket fd and which events
 341  *              happened.
 342  *
 343  *      This function takes a pollfd that has POLLIN or POLLOUT activity and
 344  *      services it according to the state of the associated
 345  *      struct libwebsocket.
 346  *
 347  *      The one call deals with all "service" that might happen on a socket
 348  *      including listen accepts, http files as well as websocket protocol.
 349  *
 350  *      If a pollfd says it has something, you can just pass it to
 351  *      libwebsocket_serice_fd() whether it is a socket handled by lws or not.
 352  *      If it sees it is a lws socket, the traffic will be handled and
 353  *      pollfd->revents will be zeroed now.
 354  *
 355  *      If the socket is foreign to lws, it leaves revents alone.  So you can
 356  *      see if you should service yourself by checking the pollfd revents
 357  *      after letting lws try to service it.
 358  */
 359
 360 LWS_VISIBLE int
 361 libwebsocket_service_fd(struct libwebsocket_context *context,
 362                                         struct libwebsocket_pollfd *pollfd)
 363 {
 364         struct libwebsocket *wsi;
 365         int n, m;
 366         lws_sockfd_type mfd;
 367 #if LWS_POSIX
 368         int listen_socket_fds_index = 0;
 369 #endif
 370         time_t now;
 371         int timed_out = 0;
 372         lws_sockfd_type our_fd = 0;
 373         char draining_flow = 0;
 374         int more;
 375         struct lws_tokens eff_buf;
 376         unsigned int pending = 0;
 377
 378 #if LWS_POSIX
 379         if (context->listen_service_fd)
 380                 listen_socket_fds_index = wsi_from_fd(context,context->listen_service_fd)->position_in_fds_table;
 381 #endif
 382          /*
 383          * you can call us with pollfd = NULL to just allow the once-per-second
 384          * global timeout checks; if less than a second since the last check
 385          * it returns immediately then.
 386          */
 387
 388         time(&now);
 389
 390         /* TODO: if using libev, we should probably use timeout watchers... */
 391         if (context->last_timeout_check_s != now) {
 392                 context->last_timeout_check_s = now;
 393
 394                 lws_plat_service_periodic(context);
 395
 396                 /* global timeout check once per second */
 397
 398                 if (pollfd)
 399                         our_fd = pollfd->fd;
 400
 401                 for (n = 0; n < context->fds_count; n++) {
 402                         mfd = context->fds[n].fd;
 403                         wsi = wsi_from_fd(context, mfd);
 404                         if (!wsi)
 405                                 continue;
 406
 407                         if (libwebsocket_service_timeout_check(context, wsi, now))
 408                                 /* he did time out... */
 409                                 if (mfd == our_fd) {
 410                                         /* it was the guy we came to service! */
 411                                         timed_out = 1;
 412                                         /* he's gone, no need to mark as handled */
 413                                 }
 414                 }
 415         }
 416
 417         /* the socket we came to service timed out, nothing to do */
 418         if (timed_out)
 419                 return 0;
 420
 421         /* just here for timeout management? */
 422         if (pollfd == NULL)
 423                 return 0;
 424
 425         /* no, here to service a socket descriptor */
 426         wsi = wsi_from_fd(context, pollfd->fd);
 427         if (wsi == NULL)
 428                 /* not lws connection ... leave revents alone and return */
 429                 return 0;
 430
 431         /*
 432          * so that caller can tell we handled, past here we need to
 433          * zero down pollfd->revents after handling
 434          */
 435
 436 #if LWS_POSIX
 437         /*
 438          * deal with listen service piggybacking
 439          * every listen_service_modulo services of other fds, we
 440          * sneak one in to service the listen socket if there's anything waiting
 441          *
 442          * To handle connection storms, as found in ab, if we previously saw a
 443          * pending connection here, it causes us to check again next time.
 444          */
 445
 446         if (context->listen_service_fd && pollfd !=
 447                                        &context->fds[listen_socket_fds_index]) {
 448                 context->listen_service_count++;
 449                 if (context->listen_service_extraseen ||
 450                                 context->listen_service_count ==
 451                                                context->listen_service_modulo) {
 452                         context->listen_service_count = 0;
 453                         m = 1;
 454                         if (context->listen_service_extraseen > 5)
 455                                 m = 2;
 456                         while (m--) {
 457                                 /*
 458                                  * even with extpoll, we prepared this
 459                                  * internal fds for listen
 460                                  */
 461                                 n = lws_poll_listen_fd(&context->fds[listen_socket_fds_index]);
 462                                 if (n > 0) { /* there's a conn waiting for us */
 463                                         libwebsocket_service_fd(context,
 464                                                 &context->
 465                                                   fds[listen_socket_fds_index]);
 466                                         context->listen_service_extraseen++;
 467                                 } else {
 468                                         if (context->listen_service_extraseen)
 469                                                 context->
 470                                                      listen_service_extraseen--;
 471                                         break;
 472                                 }
 473                         }
 474                 }
 475
 476         }
 477
 478         /* handle session socket closed */
 479
 480         if ((!(pollfd->revents & LWS_POLLIN)) &&
 481                         (pollfd->revents & LWS_POLLHUP)) {
 482
 483                 lwsl_debug("Session Socket %p (fd=%d) dead\n",
 484                                                        (void *)wsi, pollfd->fd);
 485
 486                 goto close_and_handled;
 487         }
 488 #endif
 489
 490         /* okay, what we came here to do... */
 491
 492         switch (wsi->mode) {
 493         case LWS_CONNMODE_HTTP_SERVING:
 494         case LWS_CONNMODE_HTTP_SERVING_ACCEPTED:
 495         case LWS_CONNMODE_SERVER_LISTENER:
 496         case LWS_CONNMODE_SSL_ACK_PENDING:
 497                 n = lws_server_socket_service(context, wsi, pollfd);
 498                 if (n < 0)
 499                         goto close_and_handled;
 500                 pending = lws_ssl_pending(wsi);
 501                 if (pending)
 502                         goto handle_pending;
 503                 goto handled;
 504
 505         case LWS_CONNMODE_WS_SERVING:
 506         case LWS_CONNMODE_WS_CLIENT:
 507         case LWS_CONNMODE_HTTP2_SERVING:
 508
 509                 /* the guy requested a callback when it was OK to write */
 510
 511                 if ((pollfd->revents & LWS_POLLOUT) &&
 512                     (wsi->state == WSI_STATE_ESTABLISHED ||
 513                      wsi->state == WSI_STATE_HTTP2_ESTABLISHED ||
 514                      wsi->state == WSI_STATE_HTTP2_ESTABLISHED_PRE_SETTINGS ||
 515                      wsi->state == WSI_STATE_RETURNED_CLOSE_ALREADY ||
 516                      wsi->state == WSI_STATE_FLUSHING_STORED_SEND_BEFORE_CLOSE) &&
 517                            lws_handle_POLLOUT_event(context, wsi, pollfd)) {
 518                         if (wsi->state == WSI_STATE_RETURNED_CLOSE_ALREADY)
 519                                 wsi->state = WSI_STATE_FLUSHING_STORED_SEND_BEFORE_CLOSE;
 520                         lwsl_info("libwebsocket_service_fd: closing\n");
 521                         goto close_and_handled;
 522                 }
 523
 524                 if (wsi->rxflow_buffer &&
 525                               (wsi->rxflow_change_to & LWS_RXFLOW_ALLOW)) {
 526                         lwsl_info("draining rxflow\n");
 527                         /* well, drain it */
 528                         eff_buf.token = (char *)wsi->rxflow_buffer +
 529                                                 wsi->rxflow_pos;
 530                         eff_buf.token_len = wsi->rxflow_len - wsi->rxflow_pos;
 531                         draining_flow = 1;
 532                         goto drain;
 533                 }
 534
 535                 /* any incoming data ready? */
 536
 537                 if (!(pollfd->revents & LWS_POLLIN))
 538                         break;
 539 read:
 540
 541                 eff_buf.token_len = lws_ssl_capable_read(context, wsi,
 542                                 context->service_buffer,
 543                                                pending?pending:sizeof(context->service_buffer));
 544                 switch (eff_buf.token_len) {
 545                 case 0:
 546                         lwsl_info("service_fd: closing due to 0 length read\n");
 547                         goto close_and_handled;
 548                 case LWS_SSL_CAPABLE_MORE_SERVICE:
 549                         lwsl_info("SSL Capable more service\n");
 550                         n = 0;
 551                         goto handled;
 552                 case LWS_SSL_CAPABLE_ERROR:
 553                         lwsl_info("Closing when error\n");
 554                         goto close_and_handled;
 555                 }
 556
 557                 /*
 558                  * give any active extensions a chance to munge the buffer
 559                  * before parse.  We pass in a pointer to an lws_tokens struct
 560                  * prepared with the default buffer and content length that's in
 561                  * there.  Rather than rewrite the default buffer, extensions
 562                  * that expect to grow the buffer can adapt .token to
 563                  * point to their own per-connection buffer in the extension
 564                  * user allocation.  By default with no extensions or no
 565                  * extension callback handling, just the normal input buffer is
 566                  * used then so it is efficient.
 567                  */
 568
 569                 eff_buf.token = (char *)context->service_buffer;
 570 drain:
 571
 572                 do {
 573
 574                         more = 0;
 575
 576                         m = lws_ext_callback_for_each_active(wsi,
 577                                 LWS_EXT_CALLBACK_PACKET_RX_PREPARSE, &eff_buf, 0);
 578                         if (m < 0)
 579                                 goto close_and_handled;
 580                         if (m)
 581                                 more = 1;
 582
 583                         /* service incoming data */
 584
 585                         if (eff_buf.token_len) {
 586                                 n = libwebsocket_read(context, wsi,
 587                                         (unsigned char *)eff_buf.token,
 588                                                             eff_buf.token_len);
 589                                 if (n < 0) {
 590                                         /* we closed wsi */
 591                                         n = 0;
 592                                         goto handled;
 593                                 }
 594                         }
 595
 596                         eff_buf.token = NULL;
 597                         eff_buf.token_len = 0;
 598                 } while (more);
 599
 600                 pending = lws_ssl_pending(wsi);
 601                 if (pending) {
 602 handle_pending:
 603                         pending = pending > sizeof(context->service_buffer)?
 604                                 sizeof(context->service_buffer):pending;
 605                         goto read;
 606                 }
 607
 608                 if (draining_flow && wsi->rxflow_buffer &&
 609                                  wsi->rxflow_pos == wsi->rxflow_len) {
 610                         lwsl_info("flow buffer: drained\n");
 611                         lws_free2(wsi->rxflow_buffer);
 612                         /* having drained the rxflow buffer, can rearm POLLIN */
 613 #ifdef LWS_NO_SERVER
 614                         n =
 615 #endif
 616                         _libwebsocket_rx_flow_control(wsi); /* n ignored, needed for NO_SERVER case */
 617                 }
 618
 619                 break;
 620
 621         default:
 622 #ifdef LWS_NO_CLIENT
 623                 break;
 624 #else
 625                 n = lws_client_socket_service(context, wsi, pollfd);
 626                 goto handled;
 627 #endif
 628         }
 629
 630         n = 0;
 631         goto handled;
 632
 633 close_and_handled:
 634         lwsl_debug("Close and handled\n");
 635         libwebsocket_close_and_free_session(context, wsi,
 636                                                 LWS_CLOSE_STATUS_NOSTATUS);
 637         // pollfd points to something else after the close
 638         return 1;
 639
 640 handled:
 641         pollfd->revents = 0;
 642         return n;
 643 }
 644
 645 /**
 646  * libwebsocket_service() - Service any pending websocket activity
 647  * @context:    Websocket context
 648  * @timeout_ms: Timeout for poll; 0 means return immediately if nothing needed
 649  *              service otherwise block and service immediately, returning
 650  *              after the timeout if nothing needed service.
 651  *
 652  *      This function deals with any pending websocket traffic, for three
 653  *      kinds of event.  It handles these events on both server and client
 654  *      types of connection the same.
 655  *
 656  *      1) Accept new connections to our context's server
 657  *
 658  *      2) Call the receive callback for incoming frame data received by
 659  *          server or client connections.
 660  *
 661  *      You need to call this service function periodically to all the above
 662  *      functions to happen; if your application is single-threaded you can
 663  *      just call it in your main event loop.
 664  *
 665  *      Alternatively you can fork a new process that asynchronously handles
 666  *      calling this service in a loop.  In that case you are happy if this
 667  *      call blocks your thread until it needs to take care of something and
 668  *      would call it with a large nonzero timeout.  Your loop then takes no
 669  *      CPU while there is nothing happening.
 670  *
 671  *      If you are calling it in a single-threaded app, you don't want it to
 672  *      wait around blocking other things in your loop from happening, so you
 673  *      would call it with a timeout_ms of 0, so it returns immediately if
 674  *      nothing is pending, or as soon as it services whatever was pending.
 675  */
 676
 677 LWS_VISIBLE int
 678 libwebsocket_service(struct libwebsocket_context *context, int timeout_ms)
 679 {
 680         return lws_plat_service(context, timeout_ms);
 681 }
 682