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 Fragmented messages
  29 -------------------
  30
  31 To support fragmented messages you need to check for the final
  32 frame of a message with libwebsocket_is_final_fragment. This
  33 check can be combined with libwebsockets_remaining_packet_payload
  34 to gather the whole contents of a message, eg:
  35
  36     case LWS_CALLBACK_RECEIVE:
  37     {
  38         Client * const client = (Client *)user;
  39         const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
  40
  41         if (!remaining && libwebsocket_is_final_fragment(wsi)) {
  42             if (client->HasFragments()) {
  43                 client->AppendMessageFragment(in, len, 0);
  44                 in = (void *)client->GetMessage();
  45                 len = client->GetMessageLength();
  46             }
  47
  48             client->ProcessMessage((char *)in, len, wsi);
  49             client->ResetMessage();
  50         } else
  51             client->AppendMessageFragment(in, len, remaining);
  52     }
  53     break;
  54
  55 The test app llibwebsockets-test-fraggle sources also show how to
  56 deal with fragmented messages.
  57
  58 Debug Logging
  59 -------------
  60
  61 Also using lws_set_log_level api you may provide a custom callback to actually
  62 emit the log string.  By default, this points to an internal emit function
  63 that sends to stderr.  Setting it to NULL leaves it as it is instead.
  64
  65 A helper function lwsl_emit_syslog() is exported from the library to simplify
  66 logging to syslog.  You still need to use setlogmask, openlog and closelog
  67 in your user code.
  68
  69 The logging apis are made available for user code.
  70
  71 lwsl_err(...)
  72 lwsl_warn(...)
  73 lwsl_notice(...)
  74 lwsl_info(...)
  75 lwsl_debug(...)
  76
  77 The difference between notice and info is that notice will be logged by default
  78 whereas info is ignored by default.
  79
  80
  81 External Polling Loop support
  82 -----------------------------
  83
  84 libwebsockets maintains an internal poll() array for all of its
  85 sockets, but you can instead integrate the sockets into an
  86 external polling array.  That's needed if libwebsockets will
  87 cooperate with an existing poll array maintained by another
  88 server.
  89
  90 Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
  91 LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
  92 appear in the callback for protocol 0 and allow interface code to
  93 manage socket descriptors in other poll loops.
  94
  95