Discrepency in documetnation/example/implementation with get_con_from_hdl() and endpoint::close() about websocketpp

[zaphoyd]

Good question. As you've identified the real answer here is a bit more complicated than the documentation suggests. Specifically the WebSocket++ API is divided into two sections, one API that works with Endpoint objects that is synchronized by locks and refers to connections via the connection_hdl (a weak pointer). Opposite this is another API that works with Connection objects and is synchronized by the transport layer's guarantee that handlers for a given connection are never executed concurrently.

All Connection methods are safe to use inside handlers. Some Connection methods have additional locking that allows them to be safely used outside of a handler. Such methods, such as close, are wrapped by the Endpoint API that accepts a hdl, does the upgrade and forwarding to connection for you.

When the documentation says connection_ptr/get_con_from_hdl should only be used inside handlers it means that if you stick to this rule of thumb you won't end up in trouble from a threading perspective, not that literally there are no safe uses of a connection_ptr outside of a handler.

When the library is used idiomatically, get_con_from_hdl and the resulting connection_ptr never need to be used outside of a handler. Every action on a Connection that is safe to be called from anywhere is wrapped in an Endpoint method that accepts a connection_hdl.

[joesdiner]

Thanks for the quick response and clarification. I'm not using get_con_from_hdl() outside a handler so I should be fine. I just wanted to make sure there wasn't a problem in the implementation, which there isn't. I'm going to go ahead and close this issue.