[Libwebsockets] Plan for 1.6

Andy Green andy at warmcat.com
Mon Dec 14 00:07:56 CET 2015



On 12/08/2015 11:13 AM, Andy Green wrote:
>
>
> On December 7, 2015 4:12:58 PM GMT+08:00, Andy Green <andy at warmcat.com> wrote:
>>
>>
>> On December 7, 2015 3:48:23 PM GMT+08:00, Andrejs Hanins
>> <andrejs.hanins at ubnt.com> wrote:
>>> Andy,
>>>
>>> On 12/07/2015 01:13 AM, Andy Green wrote:
>>>>
>>>>
>>>> On December 7, 2015 6:10:35 AM GMT+08:00, Roger Light
>>> <roger at atchoo.org> wrote:
>>>>> Hi Andy,
>>>>>
>>>> >From what I can see you've covered the bases pretty well. The
>> testing
>>>>> I've done so far is all going fine.
>>>>>
>>>>> Keeping the same soversion doesn't feel right, but I'm not sure
>> what
>>>>> the best thing to do is.
>>>>>
>>>>> If LWS_WITH_OLD_API_WRAPPERS=off, then the ABI no longer matches
>> and
>>>>> so soversion should be bumped.
>>>>>
>>>>> If LWS_WITH_OLD_API_WRAPPERS=on, then the ABI still matches and
>>> there
>>>>> is no need for the soversion to be bumped.
>>>>>
>>>>> That kind of implies that the soversion should be set based on
>>> whether
>>>>> LWS_WITH_OLD_API_WRAPPERS is set or not, which doesn't feel exactly
>>>>> right.
>>>>>
>>>>> Could I suggest setting LWS_WITH_OLD_API_WRAPPERS=on by default,
>> but
>>>>> adding a #warning to the wrapper block to say that the old API is
>>>>> deprecated and will be removed in 1.7 (or whatever).
>>>>>
>>>>> If you keep LWS_WITH_OLD_API_WRAPPERS=off by default, I think the
>>>>> soversion should be bumped.
>>>>
>>>> Yeah you are right we need to do something more... when I think
>> about
>>> it from the perspective of the new api user, rather than it being
>> about
>>> compatibility, he needs to assert that he wants to bind to a library
>>> version with the new apis.  So he needs an soname bump for that,
>>> otherwise he thinks he will be content with a library from months ago
>>> with no new api exports.
>>>>
>>>> The situation is not we bump it because we broke binary
>> compatibility
>>> (with LWS_WITH_OLD_API_WRAPPERS on) but because we added some apis.
>>>
>>> Any change to lws_callback_reasons (except appending to the end)
>> breaks
>>> ABI, because enum values get shifted.
>>> There were no SOVERSION bump since February despite the fact
>>> LWS_CALLBACK_RECEIVE_PONG enum value was added
>>> in October. I personally hit this bug when older LWS lib didn't work
>>> with client code compiled using
>>> newer headers. So this is yet another reason to bump the SOVERSION and
>>> make sure it bumped every time
>>> when some public enum is shifted by inserting a value in between.
>>
>> Ouch... actually that's not new to me I have been adding things at the
>> end.
>>
>> It was contributed and I didn't spot it.
>
> I added this
>
> http://git.libwebsockets.org/cgi-bin/cgit/libwebsockets/commit/?id=dc0731b3a5581161f031dcecc3635bb700ad09eb
>
> ...which converts all enums we control publicly to be set to explicit numbers (so it's painful / noticeable to ripple any unwanted number change along), and adds comments on the affected enums to only add things at the indicated place on each.
>
>> Oh well I guess it solves what to do.
>
> I also bumped the soname.
>
> I'll wait a bit and if no new crises issue 1.6 this week.

Actually thinking about it if there's an soname bump, there's one nasty 
api irregularity left we should also tackle now then, and get it over with.

I added two related patches, the first one abstracts getting the 
lws_context from a wsi into lws_get_ctx(wsi)

https://github.com/warmcat/libwebsockets/commit/8203be6742d8187cd3d3c0f9007c64f4f5f67c08

The second one

https://github.com/warmcat/libwebsockets/commit/d2ac22c27abf34d3cccb3a6fe1e2c6d92123f436

makes the user protocols struct really const, the two extra members we 
used to write to are removed.  The cost of that is three apis that used 
to be able to only take a pointer to a protocol must now also take a 
pointer to the context in order to work, (and every struct lws gains a 
context pointer).

  LWS_VISIBLE LWS_EXTERN int
-lws_callback_on_writable_all_protocol(const struct lws_protocols 
*protocol);
+lws_callback_on_writable_all_protocol(const struct lws_context *context,
+                                     const struct lws_protocols *protocol);

  LWS_VISIBLE LWS_EXTERN int
-lws_callback_all_protocol(const struct lws_protocols *protocol, int 
reason);
+lws_callback_all_protocol(struct lws_context *context,
+                         const struct lws_protocols *protocol, int reason);

  LWS_VISIBLE LWS_EXTERN void
-lws_rx_flow_allow_all_protocol(const struct lws_protocols *protocol);
+lws_rx_flow_allow_all_protocol(const struct lws_context *context,
+                              const struct lws_protocols *protocol);

consequently I can't provide compatibility helpers for these three apis 
any more (they simply cannot work with just a const protocol * now), so 
the compatibility helpers are removed.

People who are updating to 1.6 will have to fix up any usage of those 
three apis (it is written up in changelog).  It's painful, but we bump 
the soname anyway and as Bruce found, it's already very painful having 
non-obvious non-constness in something you would really reasonably think 
was const.

The user const protocols struct can cleanly be reused serially or 
simultaneously between different contexts simply after this.

-Andy

> -Andy
>
>> -Andy
>>
>>>>
>>>> We could bump the soname and create a symlink with the old soname
>>> when LWS_WITH_OLD_API_WRAPPERS=on, like libwebsockets.so.5 ->
>>> libwebsockets.so.6... how does that sound?
>>>>
>>>> If it has problems we're just left with bumping the soname and
>>> explaining it's completely backwards-compatible when built with
>>> LWS_WITH_OLD_API_WRAPPERS.
>>>>
>>>> -Andy
>>>>
>>>>> Cheers,
>>>>>
>>>>> Roger
>>>>>
>>>>> On Sun, Dec 6, 2015 at 3:22 AM, Andy Green <andy at warmcat.com>
>> wrote:
>>>>>> Hi -
>>>>>>
>>>>>> Just a heads-up I'm planning to release 1.6 shortly.
>>>>>>
>>>>>> Although it's a short time since 1.5, we have a lot of new things.
>>>>>>
>>>>>>   - api rationalization (I explain in a moment)
>>>>>>
>>>>>>   - mingw and clang compatibility working
>>>>>>
>>>>>>   - mbed3 support usable (+/- the remaining mbed3 "500ms bug" they
>>> are
>>>>>> working on fixing - https://github.com/ARMmbed/sockets/issues/38 )
>>>>>>
>>>>>>   - several fixed mainly on windows stuff
>>>>>>
>>>>>>   - big refactor on the test apps including an official pthreads
>>>>> example
>>>>>>
>>>>>>   - cleaned out almost all windows build warnings (couple of
>>>>> deprecated api
>>>>>> warnings is all that is left)
>>>>>>
>>>>>>   - zero defects on coverity (3 small ones fixed)... they have an
>>>>> interesting
>>>>>> graph "average OSS defect density" is supposedly 0.35 per 100KLOC,
>>>>> our
>>>>>> density started at 0.05 a year ago when Joakim set up coverity and
>>>>> now is
>>>>>> zero.  (It's not the same as zero bugs unfortunately, but it
>>>>> hopefully means
>>>>>> something).
>>>>>>
>>>>>>
>>>>>> The goal of the api rationalization was to get rid of the
>> confusing
>>>>>> libwebsocket_ / libwebsockets_ api and struct prefixes and only
>> use
>>>>> lws for
>>>>>> everything.
>>>>>>
>>>>>> If you want to align your code with that, you can do it with
>>>>>>
>>>>>>   - /libwebsocket_/lws_/
>>>>>>   - /libwebsockets_/lws_/
>>>>>>   - /struct\ libwebsocket/struct\ lws/
>>>>>>
>>>>>> If you don't want to, or can't, update your user code, there are
>>> two
>>>>> layers
>>>>>> of backwards compatibility.... #defines in libwebsockets.h mean
>> you
>>>>> can just
>>>>>> rebuild your app without changing anything (ie, keep the old api
>>>>> names) and
>>>>>> you're good to go.
>>>>>>
>>>>>> If you are building the library for distro type usage, and / or
>> you
>>>>> can't
>>>>>> rebuild your app, you can enable a new cmake define
>>>>>> -DLWS_WITH_OLD_API_WRAPPERS=1
>>>>>>
>>>>>> This causes the library to build wrapper functions with the old
>>>>> names, while
>>>>>> also supporting the new names so you are compatible with both. For
>>>>> that
>>>>>> reason there's no soname bump involved.
>>>>>>
>>>>>> Any testing of HEAD would be helpful ^^
>>>>>>
>>>>>> -Andy
>>>>>> _______________________________________________
>>>>>> Libwebsockets mailing list
>>>>>> Libwebsockets at ml.libwebsockets.org
>>>>>> http://ml.libwebsockets.org/mailman/listinfo/libwebsockets
>>>>
>>>> _______________________________________________
>>>> Libwebsockets mailing list
>>>> Libwebsockets at ml.libwebsockets.org
>>>> http://ml.libwebsockets.org/mailman/listinfo/libwebsockets
>>>>
>>> _______________________________________________
>>> Libwebsockets mailing list
>>> Libwebsockets at ml.libwebsockets.org
>>> http://ml.libwebsockets.org/mailman/listinfo/libwebsockets
>>
>> _______________________________________________
>> Libwebsockets mailing list
>> Libwebsockets at ml.libwebsockets.org
>> http://ml.libwebsockets.org/mailman/listinfo/libwebsockets
>
> _______________________________________________
> Libwebsockets mailing list
> Libwebsockets at ml.libwebsockets.org
> http://ml.libwebsockets.org/mailman/listinfo/libwebsockets
>



More information about the Libwebsockets mailing list