WIP: Add graceful cancel to cancel scopes

[nmalaguti]

See https://trio.discourse.group/t/graceful-shutdown/93/19?u=nmalaguti for the intended behavior.

No tests yet, just some code to illustrate intended behavior.

[codecov]

Codecov Report

Merging #941 into master will decrease coverage by 0.35%.
The diff coverage is 51.66%.

@@            Coverage Diff             @@
##           master     #941      +/-   ##
==========================================
- Coverage   99.39%   99.03%   -0.36%     
==========================================
  Files         102      102              
  Lines       12461    12249     -212     
  Branches      915      918       +3     
==========================================
- Hits        12385    12131     -254     
- Misses         56       85      +29     
- Partials       20       33      +13

Impacted Files	Coverage Δ
trio/_core/_run.py	95.8% <51.66%> (-3.92%)	⬇️
trio/_subprocess_platform/waitid.py	60.52% <0%> (-39.48%)	⬇️
trio/socket.py	92.85% <0%> (-7.15%)	⬇️
trio/_util.py	94.73% <0%> (-4.23%)	⬇️
trio/_core/_multierror.py	95.59% <0%> (-3.79%)	⬇️
trio/tests/test_file_io.py	98.21% <0%> (-1.79%)	⬇️
trio/_socket.py	98.31% <0%> (-0.88%)	⬇️
trio/testing/_trio_test.py	87.5% <0%> (-0.74%)	⬇️
trio/_highlevel_open_unix_stream.py	83.33% <0%> (-0.67%)	⬇️
trio/_core/_ki.py	98.36% <0%> (-0.13%)	⬇️
... and 48 more

[nmalaguti]

It looks like self.cancel_called is in this if statement to ensure that raising Cancelled won't be caught here unless scope.cancel() was called. Looking at the logic in _pending_cancel_scope it looks like you can't return a scope unless that is already true, so this check is redundant.

I have removed it because there are now cases where you can be cancelled gracefully without having been explicitly cancelled.

[nmalaguti]

@oremanj I was surprised at how simple this was to implement, and it turns out it's because you've been doing a ton of work in the cancellation space.

Seeing how this relates to #886, #885, #910, and #147, I feel like I didn't do enough research before embarking on this change.

Also I just noticed you have an alternate approach in #921. I'd love to discuss further the differences between them.

[Tronic]

This wording is hard to understand and should be clarified.