1# `lws_sul` scheduler api 2 3Since v3.2 lws no longer requires periodic checking for timeouts and 4other events. A new system was refactored in where future events are 5scheduled on to a single, unified, sorted linked-list in time order, 6with everything at us resolution. 7 8This makes it very cheap to know when the next scheduled event is 9coming and restrict the poll wait to match, or for event libraries 10set a timer to wake at the earliest event when returning to the 11event loop. 12 13Everything that was checked periodically was converted to use `lws_sul` 14and schedule its own later event. The end result is when lws is idle, 15it will stay asleep in the poll wait until a network event or the next 16scheduled `lws_sul` event happens, which is optimal for power. 17 18# Side effect for older code 19 20If your older code uses `lws_service_fd()`, it used to be necessary 21to call this with a NULL pollfd periodically to indicate you wanted 22to let the background checks happen. `lws_sul` eliminates the whole 23concept of periodic checking and NULL is no longer a valid pollfd 24value for this and related apis. 25 26# Using `lws_sul` in user code 27 28See `minimal-http-client-multi` for an example of using the `lws_sul` 29scheduler from your own code; it uses it to spread out connection 30attempts so they are staggered in time. You must create an 31`lws_sorted_usec_list_t` object somewhere, eg, in you own existing object. 32 33``` 34static lws_sorted_usec_list_t sul_stagger; 35``` 36 37Create your own callback for the event... the argument points to the sul object 38used when the callback was scheduled. You can use pointer arithmetic to translate 39that to your own struct when the `lws_sorted_usec_list_t` was a member of the 40same struct. 41 42``` 43static void 44stagger_cb(lws_sorted_usec_list_t *sul) 45{ 46... 47} 48``` 49 50When you want to schedule the callback, use `lws_sul_schedule()`... this will call 51it 10ms in the future 52 53``` 54 lws_sul_schedule(context, 0, &sul_stagger, stagger_cb, 10 * LWS_US_PER_MS); 55``` 56 57In the case you destroy your object and need to cancel the scheduled callback, use 58 59``` 60 lws_sul_schedule(context, 0, &sul_stagger, NULL, LWS_SET_TIMER_USEC_CANCEL); 61``` 62 63# lws_sul2 and system suspend 64 65In v4.1, alongside the existing `lws_sul` apis there is a refactor and additional 66functionality aimed at negotiating system suspend, while remaining completely 67backwards-compatible with v3.2+ lws_sul apis. 68 69Devicewide suspend is basically the withdrawal of CPU availability for an unbounded 70amount of time, so what may have been scheduled by the user code may miss its time 71slot because the cpu was down and nothing is getting serviced. Whether that is 72actively desirable, OK, a big disaster, or a failure that will be corrected at other 73layers at the cost of, eg, some additional latency, depends on the required device 74behaviours and the function of the user code that was scheduled, and its meaning to 75the system. 76 77Before v4.1, lws just offers the same scheduling service for everything both internal 78and arranged by user code, and has no way to know what is critical for the device to 79operate as intended, and so must force wake from suspend, or if for that scheduled 80event 'failure [to get the event] is an option'. 81 82For example locally-initiated periodic keepalive pings not happening may allow 83persistently dead (ie, no longer passing data) connections to remain unrenewed, but 84eventually when suspend ends for another reason, the locally-initiated PING probes 85will resume and it will be discovered and if the connectivity allows, corrected. 86 87If the device's function can handle the latency of there being no connectivity in 88suspend under those conditions until it wakes for another reason, it's OK for these 89kind of timeouts to be suppressed during suspend and basically take the power saving 90instead. If for a particular device it's intolerable to ever have a silently dead 91connection for more than a very short time compared to suspend durations, then these 92kind of timeouts must have the priority to wake the whole device from suspend so 93they continue to operate unimpeded. 94 95That is just one example, lws offers generic scheduler services the user code can 96exploit for any purpose, including mission-critical ones. The changes give the user 97code a way to tell lws if a particular scheduled event is important enough to the 98system operation to wake the system from devicewide suspend. 99 100