diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..f9989aa2 --- /dev/null +++ b/README.rst @@ -0,0 +1,72 @@ + +Useful tips for using `libwebsockets` +===================================== + +Maximum number of clients +------------------------- +There is a hard limit on the maximum number of clients the library will accept and by default it is set to **100**. +This limit can be changed by modifying the **MAX_CLIENTS** preprocessor macro in the file +**lib/private-libwebsockets.h**. The higher the limit the more memory the library will allocate at startup. + +SSL performance +--------------- +It is recommended to tweak the ciphers allowed on secure connections for performance reasons, +otherwise a slow algorithm may be selected by the two endpoints and the server could expend most of its time just +encrypting and decrypting data, severely limiting the amount of messages it will be able to handle per second. +To limit the ciphers supported on secure connections you should modify the preprocessor macro **CIPHERS_LIST_STRING** +in the file **lib/private-libwebsockets.h**. For example:: + + #define CIPHERS_LIST_STRING "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL" + +Other tweaks +------------ +There are several preprocessor macros that could be tweaked to reduce memory usage, +to increase performance or to change the behaviour of the library to suit your needs, +they are all located in the file **lib/private-libwebsockets.h**. + +Big frames +---------- +The library process data from the sockets in chunks of **4KB** (defined by the macro **MAX_USER_RX_BUFFER**), +these chunks will be passed to the client callback as **LWS_CALLBACK_RECEIVE**. +If you want to know whether you have all the data for the current frame you need to use the function +**libwebsockets_remaining_packet_payload**. + +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 like in this example:: + + case LWS_CALLBACK_RECEIVE: + { + Client * const client = (Client *)user; + const size_t remaining = libwebsockets_remaining_packet_payload(wsi); + if (0 == 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; + +HTTP requests +------------- +If your server is going to support regular HTTP requests by handling **LWS_CALLBACK_HTTP** it is recommended to +**return 1** as the result of the callback after you write the response, +this will tell the library to automatically close the connection. +Closing the connection will liberate an slot for another HTTP request, +otherwise it would be up to the browser to close the connection, +which could be an issue because the library has a hard limit on the number of open connections, as explained before.