I've had a very similar experience a few weeks ago and even fell for the same double-userdata misunderstanding.

The documentation itself is actually good and extensive, however it feels like the authors expect its users to deeply understand the library itself. It is also harder to find some "Getting Started" docs as most provided examples felt way too bloated coming from a nodejs/ws background. Compared to the other library[1] I was considering, it took much longer to get even a simple "echo" server running.

However having used lws for some time now, I am really happy with it! The API is very clean, mostly intuitive and provides everything you need, without feeling bloated or becoming too verbose. Sometimes documentation still feels a bit harder to find, but it can be figured out eventually. One great feature for me was being able to accept both WebSocket as well as raw TCP connections on the same port, this is extremely easy and just required settings the flag LWS_SERVER_OPTION_FALLBACK_TO_RAW.

I encountered other hiccups. They are fully documented and completely valid, but were really confusing to me as a first-time user:

* Sending data requires a specific memory layout[2] – namely having to allocate memory for the websocket header youself before the actual message you want to send. This gave me confusing segfaults in the beginning.

* Sending data / responding to a client message will probably (but not always) fail when just naively using "lws_write()". To correctly send data you need to manually queue your message data, request the "ON_WRITABLE" callback[3] and only then actually send.

[1]: https://github.com/Theldus/wsServer

[2]: https://libwebsockets.org/lws-api-doc-v3.0-stable/html/group... (see the "IMPORTANT NOTICE")

[3]: https://libwebsockets.org/lws-api-doc-main/html/group__callb...

user:	numpad
created:	July 14, 2014
karma:	12