mirror of
https://github.com/warmcat/libwebsockets.git
synced 2025-03-09 00:00:04 +01:00

As per http://libwebsockets.org/trac/ticket/10 BSD doesn't support setting keepalive info per-socket Signed-off-by: Andy Green <andy.green@linaro.org>
190 lines
6.9 KiB
Text
190 lines
6.9 KiB
Text
Daemonization
|
|
-------------
|
|
|
|
There's a helper api lws_daemonize built by default that does everything you
|
|
need to daemonize well, including creating a lock file. If you're making
|
|
what's basically a daemon, just call this early in your init to fork to a
|
|
headless background process and exit the starting process.
|
|
|
|
Notice stdout, stderr, stdin are all redirected to /dev/null to enforce your
|
|
daemon is headless, so you'll need to sort out alternative logging, by, eg,
|
|
syslog.
|
|
|
|
|
|
Maximum number of connections
|
|
-----------------------------
|
|
|
|
The maximum number of connections the library can deal with is decided when
|
|
it starts by querying the OS to find out how many file descriptors it is
|
|
allowed to open (1024 on Fedora for example). It then allocates arrays that
|
|
allow up to that many connections, minus whatever other file descriptors are
|
|
in use by the user code.
|
|
|
|
If you want to restrict that allocation, or increase it, you can use ulimit or
|
|
similar to change the avaiable number of file descriptors, and when restarted
|
|
libwebsockets will adapt accordingly.
|
|
|
|
|
|
Libwebsockets is singlethreaded
|
|
-------------------------------
|
|
|
|
Directly performing websocket actions from other threads is not allowed.
|
|
Aside from the internal data being inconsistent in forked() processes,
|
|
the scope of a wsi (struct websocket) can end at any time during service
|
|
with the socket closing and the wsi freed.
|
|
|
|
Websocket write activities should only take place in the
|
|
"LWS_CALLBACK_SERVER_WRITEABLE" callback as described below.
|
|
|
|
Only live connections appear in the user callbacks, so this removes any
|
|
possibility of trying to used closed and freed wsis.
|
|
|
|
If you need to service other socket or file descriptors as well as the
|
|
websocket ones, you can combine them together with the websocket ones
|
|
in one poll loop, see "External Polling Loop support" below, and
|
|
still do it all in one thread / process context.
|
|
|
|
|
|
Only send data when socket writeable
|
|
------------------------------------
|
|
|
|
You should only send data on a websocket connection from the user callback
|
|
"LWS_CALLBACK_SERVER_WRITEABLE" (or "LWS_CALLBACK_CLIENT_WRITEABLE" for
|
|
clients).
|
|
|
|
If you want to send something, do not just send it but request a callback
|
|
when the socket is writeable using
|
|
|
|
- libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or
|
|
- libwebsocket_callback_on_writable_all_protocol(protocol) for all connections
|
|
using that protocol to get a callback when next writeable.
|
|
|
|
Usually you will get called back immediately next time around the service
|
|
loop, but if your peer is slow or temporarily inactive the callback will be
|
|
delayed accordingly. Generating what to write and sending it should be done
|
|
in the ...WRITEABLE callback.
|
|
|
|
See the test server code for an example of how to do this.
|
|
|
|
|
|
Fragmented messages
|
|
-------------------
|
|
|
|
To support fragmented messages you need to check for the final
|
|
frame of a message with libwebsocket_is_final_fragment. This
|
|
check can be combined with libwebsockets_remaining_packet_payload
|
|
to gather the whole contents of a message, eg:
|
|
|
|
case LWS_CALLBACK_RECEIVE:
|
|
{
|
|
Client * const client = (Client *)user;
|
|
const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
|
|
|
|
if (!remaining && libwebsocket_is_final_fragment(wsi)) {
|
|
if (client->HasFragments()) {
|
|
client->AppendMessageFragment(in, len, 0);
|
|
in = (void *)client->GetMessage();
|
|
len = client->GetMessageLength();
|
|
}
|
|
|
|
client->ProcessMessage((char *)in, len, wsi);
|
|
client->ResetMessage();
|
|
} else
|
|
client->AppendMessageFragment(in, len, remaining);
|
|
}
|
|
break;
|
|
|
|
The test app llibwebsockets-test-fraggle sources also show how to
|
|
deal with fragmented messages.
|
|
|
|
|
|
Debug Logging
|
|
-------------
|
|
|
|
Also using lws_set_log_level api you may provide a custom callback to actually
|
|
emit the log string. By default, this points to an internal emit function
|
|
that sends to stderr. Setting it to NULL leaves it as it is instead.
|
|
|
|
A helper function lwsl_emit_syslog() is exported from the library to simplify
|
|
logging to syslog. You still need to use setlogmask, openlog and closelog
|
|
in your user code.
|
|
|
|
The logging apis are made available for user code.
|
|
|
|
lwsl_err(...)
|
|
lwsl_warn(...)
|
|
lwsl_notice(...)
|
|
lwsl_info(...)
|
|
lwsl_debug(...)
|
|
|
|
The difference between notice and info is that notice will be logged by default
|
|
whereas info is ignored by default.
|
|
|
|
|
|
External Polling Loop support
|
|
-----------------------------
|
|
|
|
libwebsockets maintains an internal poll() array for all of its
|
|
sockets, but you can instead integrate the sockets into an
|
|
external polling array. That's needed if libwebsockets will
|
|
cooperate with an existing poll array maintained by another
|
|
server.
|
|
|
|
Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
|
|
LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
|
|
appear in the callback for protocol 0 and allow interface code to
|
|
manage socket descriptors in other poll loops.
|
|
|
|
|
|
Using with in c++ apps
|
|
----------------------
|
|
|
|
The library is ready for use by C++ apps. You can get started quickly by
|
|
copying the test server
|
|
|
|
$ cp test-server/test-server.c test.cpp
|
|
|
|
and building it in C++ like this
|
|
|
|
$ g++ -DINSTALL_DATADIR=\"/usr/share\" -ocpptest test.cpp -lwebsockets
|
|
|
|
INSTALL_DATADIR is only needed because the test server uses it as shipped, if
|
|
you remove the references to it in your app you don't need to define it on
|
|
the g++ line either.
|
|
|
|
|
|
Availability of header information
|
|
----------------------------------
|
|
|
|
From v1.2 of the library onwards, the HTTP header content is free()d as soon
|
|
as the websocket connection is established. For websocket servers, you can
|
|
copy interesting headers by handling LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION
|
|
callback, for clients there's a new callback just for this purpose
|
|
LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH.
|
|
|
|
|
|
TCP Keepalive
|
|
-------------
|
|
|
|
It is possible for a connection which is not being used to send to die
|
|
silently somewhere between the peer and the side not sending. In this case
|
|
by default TCP will just not report anything and you will never get any more
|
|
incoming data or sign the link is dead until you try to send.
|
|
|
|
To deal with getting a notification of that situation, you can choose to
|
|
enable TCP keepalives on all libwebsockets sockets, when you create the
|
|
context.
|
|
|
|
To enable keepalive, set the ka_time member of the context creation parameter
|
|
struct to a nonzero value (in seconds) at context creation time. You should
|
|
also fill ka_probes and ka_interval in that case.
|
|
|
|
With keepalive enabled, the TCP layer will send control packets that should
|
|
stimulate a response from the peer without affecting link traffic. If the
|
|
response is not coming, the socket will announce an error at poll() forcing
|
|
a close.
|
|
|
|
Note that BSDs don't support keepalive time / probes / inteveral per-socket
|
|
like Linux does. On those systems you can enable keepalive by a nonzero
|
|
value in ka_time, but the systemwide kernel settings for the time / probes/
|
|
interval are used, regardless of what nonzero value is in ka_time.
|