jobs: prevent parallel execution and plugin specific scheduler

[Exirel]

Closes #1144

Description

Initially, it was only about preventing parallel execution of jobs, but then I realized I needed way more than that:

• changed the job object to be registered only once for any set of intervals,
• changed the job object to have similar meta-data than plugin's rules
• added a new scheduler, that can be used in a plugin-specific context (similar to the plugin's rules manager)

Also, I realized that the "catch up" mechanism makes no sense: either the job can be run in time, or it can't, but it won't try to run it more than once because it's late. I can see why it was like that before, but there are several problems with how it was implemented:

• the scheduler is not reliable: it ticks at best every second, at worst every now and then
• a job isn't aware of the catch up mechanism: is it late? is it on time? it can't know, so it can't adapt itself

In that regard, it's best not to over-engineer the solution, and to just take the most optimistic and safe approach: execute only once at a time, then see if it should execute again or a bit later, given the configured intervals.

And here we are, with a lot of changes for something that seem easy at first. The good news is that it was necessary anyway to work on a better documentation spec for Sopel: in the future, we'll be able to list not only rules and commands, but also jobs! But that will be for a future PR.

Checklist

• I have read CONTRIBUTING.md
• I can and do license this contribution under the EFLv2
• No issues are reported by make qa (runs make quality and make test)
• I have tested the functionality of the things this change touches

[dgw]

Not the most comprehensive review, but a start. Couple of actual questions here—for once, I'm not just playing with docstrings. 😛

[Exirel]

OK, there is more to say about the register/unregister situation in the bot.

1. bot.register expects 4 parameters (callables, jobs, urls, shutdown), but bot.unregister expects just one callable and deal with it. What is that??? I think we should remove both, and I'd argue that we should not bother with deprecation cycle in this case.
2. bot.register_* methods make sense, because they allow to register a callable, that will be transformed into some sort of object, tied to a plugin.
3. bot.unregister_* methods don't, because what we usually want is to unregister a whole plugin, not just a single function (there should be other means to do that properly, like using rule's label, or command's name)
4. In fact, these (un)register_* methods could (should?) be private, because the right interface should be about adding/removing a plugin, and not dealing with individual parts. I remember when working on plugin: new interface #1479 I had so much trouble making sense of the bot's interface approaching callables, jobs, urls, and so on
5. At some point, shutdown methods shouldn't be registered - the plugin handler can do that for us
6. Also the URL callback registration should be designed like the Rules Manager and the plugin's Scheduler, in a somewhat unified interface

It's a long process. So in this PR, I'll revert my changes on unregister, change what I did on unregister_jobs, and I'll do another PR for everything else mentioned in this comment, if that sounds good for you @dgw ?

[Exirel]

@dgw also, I'll make document sopel.tools.jobs. I'll add a big important block to tell it's all internal an stuff, but if I don't do that, I'll have trouble documenting sopel.plugins.jobs.

[Exirel]

@dgw so, you were totally right in your comments. Because I added so much docstrings, and because there was so much to fix/change/revert, I believe a "rebase" couldn't hurt in that specific case. Most of the docstrings have been updated, added, moved, or replaced, so I think you will have to re-review everything anyway.

As said earlier, I won't update the bot.unregister method again in this PR, I'll do a separate one for that, I think it's better this way. Also, I'm sorry for all the mess. I'm glad you are here doing the review, because it really makes Sopel better. Sometimes, I'm lazy, or I forget something, or I make an honest mistake. And usually, you're here to make sure it's fixed properly, and that's invaluable! ❤️

So good luck with the review, hope it won't be too difficult this time.

[dgw]

Fun times at grammar school. 😛

[Exirel]

Changes applied and fixed the docstring.

[dgw]

Another "Squash what you're gonna squash and we'll "

[Exirel]

Done as well.