wait_task_rescheduled API revision umbrella issue

[oremanj]

From discussion in chat here: https://gitter.im/python-trio/general?at=5da7d898894dee56e558319b

If we want to make wait_task_rescheduled() better, what would we want to change?

• It has a complicated calling convention with the raise_cancel callback parameter. We might be able to get rid of this now that Cancelled exceptions are stateless, provided that we also modify KeyboardInterrupt handling to inject a new task rather than waking up an existing task (as discussed at Proposal: make checkpoint_if_cancelled() sync-colored and rename it accordingly #961 (comment))
• It has a very particular contract and isn't much able to diagnose violations thereof (such as calling reschedule() twice, or returning Abort.SUCCEEDED and then calling reschedule())
• The fact that it's flexible enough for unusual cases (asynchronous cancellation, etc) makes it a bit daunting to use in simple cases.

One promising-seeming idea is to reify a "wake token" (strawman name) which must be used to wake the task (rather than passing the task object itself to trio.hazmat.reschedule()). Then the wake token could capture additional state like "did this wakeup occur yet?", and we could also move custom_sleep_data from Task to WakeToken for better scoping.

The initial impetus for the "wake token" idea involved forced wakeups when we notice a missing await (see #79, and specifically the version in bpo-30491), but we might sidestep that need by injecting an exception in the parent nursery instead, in order to have fewer special cases. Wake tokens would still be useful for making the API more forgiving if it's misused.

Other thoughts:

• Should sleeps that support synchronous cancellation use the same interface as those that don't? The former are easier to reason about, and are also the only ones that could reasonably be used with CML-style select() operations (Discussion: what's the best strategy for "nowait" and "select" operations? #242).
• If we think about this in CML terms, currently "publish" happens before the call to wait_task_rescheduled() and "unpublish" happens either in the abort_fn or in the waking task. If we start using wake tokens, the "publish" part needs to be able to stash the wake token somewhere. That means either that the "publish" logic needs to be in a callback passed to the wait_task_rescheduled equivalent, or that we need to expose the ability to create a wake token independently of sleeping on it.
• We should mine the discussion from Can we make abort functions more composable? #896, Some way to take a cancellation in one call to wait_task_rescheduled and forward it to another task #642, and Should we call the abort_fn when rescheduling in general? #315 for any other ideas we want to implement, so we can make all the breaking changes at once.