Ref #701 -- Add support for a custom executor for sychronous checks

Author: codingjoe

docs/usage.md

@@ -141,3 +141,35 @@ CustomHealthCheck        ... Unavailable: Something went wrong!
 
 Similar to the http version, a critical error will cause the command to
 quit with the exit code `1`.
+
+## Performance tweaks
+
+All checks are executed asynchronously, either via `asyncio` or via a thread pool,
+depending on the implementation of the individual checks.
+This allows for concurrent execution of the mostly IO-bound checks,
+which significantly improves the response time.
+
+The event loop's default executor is used to run synchronous checks
+(e.g. [Database][health_check.checks.Database], [Mail][health_check.checks.Mail],
+or [Storage][health_check.checks.Storage]) in a thread pool.
+This pool is usually persisted across requests. This may lead to high performance while
+permanently allocating more memory. This may be undesirable for some applications,
+especially with `S3Storage`, which uses thread-local connections.
+
+This can be mitigated by using a custom executor that creates a new thread pool for each request, which is then cleaned up after the checks are completed. This can be achieved by subclassing `HealthCheckView` and overriding the `get_executor` method to return a new `ThreadPoolExecutor` instance for each request.
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from health_check.views import HealthCheckView
+
+
+class CustomHealthCheckView(HealthCheckView):
+    @staticmethod
+    def get_executor(self):
+        with ThreadPoolExecutor(max_workers=len(self.checks)) as executor:
+            yield executor
+```
+
+This approach ensures that each request gets a fresh thread pool,
+which can help manage memory usage more effectively
+while still providing the benefits of concurrent execution for synchronous checks.

health_check/base.py

@@ -6,6 +6,7 @@
 import inspect
 import logging
 import timeit
+from concurrent.futures import Executor
 
 from health_check.exceptions import HealthCheckException
 
@@ -70,16 +71,16 @@ async def run(self) -> None:
         ...
 
     def pretty_status(self) -> str:
-        """Return human-readable status string, always 'OK' for the check itself."""
+        """Return a human-readable status string, always 'OK' for the check itself."""
         return "OK"
 
-    async def get_result(self: HealthCheck) -> HealthCheckResult:
+    async def get_result(self, executor: Executor | None = None) -> HealthCheckResult:
         loop = asyncio.get_running_loop()
         start = timeit.default_timer()
         try:
             await self.run() if inspect.iscoroutinefunction(
                 self.run
-            ) else await loop.run_in_executor(None, self.run)
+            ) else await loop.run_in_executor(executor, self.run)
         except HealthCheckException as e:
             error = e
         except BaseException:

health_check/checks.py

@@ -194,11 +194,11 @@ async def run(self):
 @dataclasses.dataclass
 class Mail(HealthCheck):
     """
-    Check that mail backend is able to open and close connection.
+    Check that an email backend is able to open and close the connection.
 
     Args:
         backend: The email backend to test against.
-        timeout: Timeout for connection to mail server in seconds.
+        timeout: Timeout for connection to an email server in seconds.
 
     """
 
@@ -231,7 +231,7 @@ class Storage(HealthCheck):
     """
     Check file storage backends by saving, reading, and deleting a test file.
 
-    It can be setup multiple times for different storage backends if needed.
+    It can be set up multiple times for different storage backends if needed.
 
     Args:
         alias: The alias of the storage backend to check.

health_check/views.py

@@ -1,7 +1,9 @@
 import asyncio
+import contextlib
 import datetime
 import re
 import typing
+from concurrent.futures import Executor
 
 from django.db import transaction
 from django.http import HttpResponse, JsonResponse
@@ -111,9 +113,10 @@ async def dispatch(self, request, *args, **kwargs):
 
     @method_decorator(never_cache)
     async def get(self, request, *args, **kwargs):
-        self.results = await asyncio.gather(
-            *(check.get_result() for check in self.get_checks())
-        )
+        with contextlib.contextmanager(self.get_executor)() as executor:
+            self.results = await asyncio.gather(
+                *(check.get_result(executor) for check in self.get_checks())
+            )
         has_errors = any(result.error for result in self.results)
         status_code = 500 if has_errors else 200
         format_override = request.GET.get("format")
@@ -159,6 +162,21 @@ def get_context_data(self, **kwargs):
             "errors": any(result.error for result in self.results),
         }
 
+    def get_executor(self) -> typing.Generator[Executor | None, None, None]:
+        """
+        Yield an executor to run synchronous checks.
+
+        Yield None to use the event loop's default executor.
+
+        Example:
+            @staticmethod
+            def get_executor():
+                with ThreadPoolExecutor(max_workers=5) as executor:
+                    yield executor
+
+        """
+        yield None
+
     def render_to_response_json(self, status):
         """Return JSON response with health check results."""
         return JsonResponse(
@@ -170,7 +188,7 @@ def render_to_response_json(self, status):
         )
 
     def render_to_response_text(self, status):
-        """Return plain text response with health check results."""
+        """Return a plain text response with health check results."""
         lines = (
             f"{repr(result.check)}: {'OK' if not result.error else str(result.error)}"
             for result in self.results

mkdocs.yml

@@ -32,6 +32,7 @@ plugins:
             - https://psutil.readthedocs.io/en/stable/objects.inv
             - https://django-storages.readthedocs.io/en/latest/objects.inv
             - https://redis.readthedocs.io/en/stable/objects.inv
+            - https://django-storages.readthedocs.io/en/stable/objects.inv
 theme:
   name: material
   logo: images/icon.svg