README.coding

   1 Daemonization
   2 -------------
   3
   4 There's a helper api lws_daemonize built by default that does everything you
   5 need to daemonize well, including creating a lock file.  If you're making
   6 what's basically a daemon, just call this early in your init to fork to a
   7 headless background process and exit the starting process.
   8
   9 Notice stdout, stderr, stdin are all redirected to /dev/null to enforce your
  10 daemon is headless, so you'll need to sort out alternative logging, by, eg,
  11 syslog.
  12
  13
  14 Maximum number of connections
  15 -----------------------------
  16
  17 The maximum number of connections the library can deal with is decided when
  18 it starts by querying the OS to find out how many file descriptors it is
  19 allowed to open (1024 on Fedora for example).  It then allocates arrays that
  20 allow up to that many connections, minus whatever other file descriptors are
  21 in use by the user code.
  22
  23 If you want to restrict that allocation, or increase it, you can use ulimit or
  24 similar to change the avaiable number of file descriptors, and when restarted
  25 libwebsockets will adapt accordingly.
  26
  27
  28 Libwebsockets is singlethreaded
  29 -------------------------------
  30
  31 Directly performing websocket actions from other threads is not allowed.
  32 Aside from the internal data being inconsistent in forked() processes,
  33 the scope of a wsi (struct websocket) can end at any time during service
  34 with the socket closing and the wsi freed.
  35
  36 Websocket write activities should only take place in the
  37 "LWS_CALLBACK_SERVER_WRITEABLE" callback as described below.
  38
  39 Only live connections appear in the user callbacks, so this removes any
  40 possibility of trying to used closed and freed wsis.
  41
  42 If you need to service other socket or file descriptors as well as the
  43 websocket ones, you can combine them together with the websocket ones
  44 in one poll loop, see "External Polling Loop support" below, and
  45 still do it all in one thread / process context.
  46
  47
  48 Only send data when socket writeable
  49 ------------------------------------
  50
  51 You should only send data on a websocket connection from the user callback
  52 "LWS_CALLBACK_SERVER_WRITEABLE" (or "LWS_CALLBACK_CLIENT_WRITEABLE" for
  53 clients).
  54
  55 If you want to send something, do not just send it but request a callback
  56 when the socket is writeable using
  57
  58  - libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or
  59  - libwebsocket_callback_on_writable_all_protocol(protocol) for all connections
  60 using that protocol to get a callback when next writeable.
  61
  62 Usually you will get called back immediately next time around the service
  63 loop, but if your peer is slow or temporarily inactive the callback will be
  64 delayed accordingly.  Generating what to write and sending it should be done
  65 in the ...WRITEABLE callback.
  66
  67 See the test server code for an example of how to do this.
  68
  69
  70 Fragmented messages
  71 -------------------
  72
  73 To support fragmented messages you need to check for the final
  74 frame of a message with libwebsocket_is_final_fragment. This
  75 check can be combined with libwebsockets_remaining_packet_payload
  76 to gather the whole contents of a message, eg:
  77
  78     case LWS_CALLBACK_RECEIVE:
  79     {
  80         Client * const client = (Client *)user;
  81         const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
  82
  83         if (!remaining && libwebsocket_is_final_fragment(wsi)) {
  84             if (client->HasFragments()) {
  85                 client->AppendMessageFragment(in, len, 0);
  86                 in = (void *)client->GetMessage();
  87                 len = client->GetMessageLength();
  88             }
  89
  90             client->ProcessMessage((char *)in, len, wsi);
  91             client->ResetMessage();
  92         } else
  93             client->AppendMessageFragment(in, len, remaining);
  94     }
  95     break;
  96
  97 The test app llibwebsockets-test-fraggle sources also show how to
  98 deal with fragmented messages.
  99
 100
 101 Debug Logging
 102 -------------
 103
 104 Also using lws_set_log_level api you may provide a custom callback to actually
 105 emit the log string.  By default, this points to an internal emit function
 106 that sends to stderr.  Setting it to NULL leaves it as it is instead.
 107
 108 A helper function lwsl_emit_syslog() is exported from the library to simplify
 109 logging to syslog.  You still need to use setlogmask, openlog and closelog
 110 in your user code.
 111
 112 The logging apis are made available for user code.
 113
 114 lwsl_err(...)
 115 lwsl_warn(...)
 116 lwsl_notice(...)
 117 lwsl_info(...)
 118 lwsl_debug(...)
 119
 120 The difference between notice and info is that notice will be logged by default
 121 whereas info is ignored by default.
 122
 123
 124 External Polling Loop support
 125 -----------------------------
 126
 127 libwebsockets maintains an internal poll() array for all of its
 128 sockets, but you can instead integrate the sockets into an
 129 external polling array.  That's needed if libwebsockets will
 130 cooperate with an existing poll array maintained by another
 131 server.
 132
 133 Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
 134 LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
 135 appear in the callback for protocol 0 and allow interface code to
 136 manage socket descriptors in other poll loops.
 137
 138