Add --timeout-graceful-shutdown parameter

[JonasKs]

Summary

This is a continuation of #1824, which intend to close:

• close How do I cancel a streaming response on shutdown? #451
• close Make force_exit configure-able from command line #675

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

---

The running_in_executor-tasks problem:

As of 1b3e737, I've removed cancellation of tasks running in executors such as those spawned through run_in_executor by using os._exit(1).

The implementation worked, but unfortunately, it crashes a lot of tests (fixable), but I am also unable to actually make a test for it, and therefor I'm unsure if it will work on all platforms.

The `os._exit` implementation

Given main.py, and commit 4b703e3:

`main.py`

import time
from fastapi import FastAPI
from starlette.background import BackgroundTasks
import uvicorn

app = FastAPI()

def z():
    print('normal sleep')
    time.sleep(10)
    print('normal awake')

@app.get('/')
async def x(background: BackgroundTasks):
    background.add_task(z)

if __name__ == '__main__':
    uvicorn.run(app, timeout_graceful_shutdown=2)

1. run the server
2. do a GET request
3. do cancel server
4. see process successfully shut down after 2 seconds instead of 10.

How ever, I'm unable to test it. The test below will finish immediately as expected, but the pytest process will run for 10 seconds.

Test file

async def app_run_in_exec(scope, receive, send):
    def long_func_to_be_cancelled():
        time.sleep(10)

    loop = asyncio.get_event_loop()
    loop.run_in_executor(None, long_func_to_be_cancelled)

@pytest.mark.anyio
async def test_thread_task_background(unused_tcp_port: int):
    """
    Ensure background tasks created with `.run_in_executor` is shut down, and not waited for.
    """
    config = Config(app=app_run_in_exec, reload=False, port=unused_tcp_port, timeout_graceful_shutdown=1)
    server: Server

    async with run_server(config) as server:
        # run a thing in an executor
        server.handle_exit(sig=signal.SIGINT, frame=None)

[Kludex]

Thanks @JonasKs 🙏

[JonasKs]

Hmm, didn't really intend for this to work well with --reload, but I can see why you would want it. I'll have to look further into it, but I won't be able to until the weekend. Please help investigate if you have time.

[JonasKs]

What happened with that comment, @Kludex ? I tried looking back to find what it was all about again..

[Kludex]

I don't know. I don't delete my comments. Was it a comment from someone else?

[JonasKs]

Yeah, someone said it didn't work properly with --reload I believe. I'll test some more this weekend, I don't really remember 😅

[oliverhaas]

The parameter works fine with --reload, e.g.

uvicorn config.asgi:application --host 0.0.0.0 --reload --reload-include '*.html' --timeout-graceful-shutdown 0

Hopefully this is not too offtopic, but hopefully useful someone ends up here looking for information like I just did.

[JonasKs]

That's a good tip, should probably be documented. Potentially --reload should set it to 0 by default.