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