Doc review

Author: rogerbinns

apsw/aio.py

@@ -37,31 +37,34 @@
     # framework as documented below.
 
     with apsw.aio.contextvar_set(apsw.aio.deadline,
-            anyio.current_time() + 10):
+        anyio.current_time() + 10):
 
-            async for row in await db.execute("SELECT  time_consuming ..."):
-                print(f"{row=}")
+        async for row in await db.execute("time consuming query ..."):
+            print(f"{row=}")
 
 
 :class:`AsyncIO`
 
-    This is the only way to set a deadline.  :exc:`TimeoutError` will
+    :code:`apsw.aio.deadline` is the only way to set a deadline.
+    :exc:`TimeoutError` will
     be raised if the deadline is exceeded.  The current time is
     available from  :meth:`asyncio.get_running_loop().time()
     <asyncio.loop.time>`
 
 :class:`Trio`
 
-    If this is set then it is used for the deadline.  :exc:`trio.TooSlowError`
-    is raised.  The current time is available from :func:`trio.current_time`.
+    If :code:`apsw.aio.deadline` is set then it is used for the
+    deadline.  :exc:`trio.TooSlowError` is raised.  The current time
+    is available from :func:`trio.current_time`.
 
     Otherwise the :func:`trio.current_effective_deadline` where the
     call is made is used.
 
 AnyIO
 
-    If this is set then it is used for the deadline.  :exc:`TimeoutError` is raised.
-    The current time is available from :func:`anyio.current_time`.
+    If :code:`apsw.aio.deadline` is set then it is used for the
+    deadline.  :exc:`TimeoutError` is raised.  The current time is
+    available from :func:`anyio.current_time`.
 
     Otherwise the :func:`anyio.current_effective_deadline` where the
     call is made is used.
@@ -71,7 +74,7 @@
 check_progress_steps: contextvars.ContextVar[int] = contextvars.ContextVar(
     "apsw.aio.check_progress_steps", default=50_000
 )
-"""How many steps between checks to check for cancellation and deadlines
+"""How many internal SQLite steps between checks for cancellation and deadlines
 
 While SQLite queries are executing, periodic checks are made to see if
 the request has been cancelled, or the deadline exceeded.  This is
@@ -94,9 +97,9 @@
 if sys.version_info >= (3, 14):
 
     def contextvar_set(var: contextvars.ContextVar[T], value: T) -> contextvars.Token[T]:
-        """wrapper for setting a contextvar during a with block
+        """Wrapper for setting a :class:`~contextvars.ContextVar` during a :code:`with` block
 
-        Python 3.14 lets you do::
+        Python 3.14+ lets you do::
 
             with var.set(value):
                 # code here
@@ -105,7 +108,7 @@ def contextvar_set(var: contextvars.ContextVar[T], value: T) -> contextvars.Toke
         This wrapper provides the same functionality for all
         Python versions::
 
-            with contextvar_set(var, value):
+            with apsw.aio.contextvar_set(var, value):
                 # code here
                 ...
 
@@ -238,7 +241,7 @@ async def _coro_for_stopasynciteration():
 
 
 class AsyncIO:
-    """Uses :mod:`asyncio` for async concurrency"""
+    """:class:`Controller <apsw.AsyncConnectionController>` for :mod:`asyncio`"""
 
     def configure(self, db: apsw.Connection):
         "Setup database, just after it is created"
@@ -323,7 +326,7 @@ def async_run_coro(self, coro: Coroutine):
     if sys.version_info < (3, 11):
 
         async def run_coro_in_loop(self, coro: Coroutine, tracker: _CallTracker, context: contextvars.Context) -> Any:
-            "executes the coro in the event loop"
+            "Executes the coro in the event loop"
 
             task = context.run(asyncio.create_task, coro)
             tracker.cancel_async_cb = task.cancel
@@ -337,7 +340,7 @@ async def run_coro_in_loop(self, coro: Coroutine, tracker: _CallTracker, context
     elif sys.version_info < (3, 12):
 
         async def run_coro_in_loop(self, coro: Coroutine, tracker: _CallTracker, context: contextvars.Context) -> Any:
-            "executes the coro in the event loop"
+            "Executes the coro in the event loop"
 
             task = context.run(asyncio.create_task, coro)
             tracker.cancel_async_cb = task.cancel
@@ -350,7 +353,7 @@ async def run_coro_in_loop(self, coro: Coroutine, tracker: _CallTracker, context
     else:
 
         async def run_coro_in_loop(self, coro: Coroutine, tracker: _CallTracker, context: contextvars.Context) -> Any:
-            "executes the coro in the event loop"
+            "Executes the coro in the event loop"
 
             # Note: we don't set cancel_async_cb back to None on exit
             # because cancelling an already completed task is doesn't
@@ -374,7 +377,7 @@ def __init__(self, *, thread_name: str = "asyncio apsw background worker"):
 
 
 class Trio:
-    """Uses |trio| for async concurrency"""
+    """:class:`Controller <apsw.AsyncConnectionController>` for |trio|"""
 
     def configure(self, db: apsw.Connection):
         "Setup database, just after it is created"
@@ -450,7 +453,7 @@ def async_run_coro(self, coro: Coroutine):
             coro.close()
 
     async def run_coro_in_loop(self, coro: Coroutine, tracker: _CallTracker):
-        "executes the coro in the event loop"
+        "Executes the coro in the event loop"
         with trio.fail_at(deadline=math.inf if tracker.deadline_loop is None else tracker.deadline_loop) as scope:
             tracker.cancel_async_cb = scope.cancel
             if tracker.is_cancelled:
@@ -467,7 +470,7 @@ def __init__(self, *, thread_name: str = "trio apsw background worker"):
 
 
 class AnyIO:
-    """Uses |anyio| for async concurrency"""
+    """:class:`Controller <apsw.AsyncConnectionController>` for |anyio|"""
 
     def configure(self, db: apsw.Connection):
         "Setup database, just after it is created"
@@ -547,7 +550,7 @@ def async_run_coro(self, coro: Coroutine):
             coro.close()
 
     async def run_coro_in_loop(self, coro: Coroutine, tracker: _CallTracker):
-        "executes coro in the event loop"
+        "Executes coro in the event loop"
 
         with anyio.fail_after(
             math.inf if tracker.deadline_loop is None else tracker.deadline_loop - anyio.current_time()

doc/async.rst

@@ -6,16 +6,18 @@ Concurrency & Async
 How SQLite concurrency works
 ----------------------------
 
-Each connection has a mutex to protect the SQLite data structure.  It
-is acquired on a call into the connection, and released on return of
-the call. The mutex can be acquired more times in the same thread,
-allowing nested calls, but cannot be acquired outside of the thread
-until the top level call in the original thread completes.
+Each connection has a lock (`mutex
+<https://en.wikipedia.org/wiki/Lock_(computer_science)>`__ to protect
+the SQLite data structure.  It is acquired on a call into the
+connection, and released on return of the call. The mutex can be
+acquired more times in the same thread, allowing nested calls, but
+cannot be acquired outside of the thread until the top level call in
+the original thread completes.
 
 This means you cannot get more concurrency per connection by using
 additional threads, although SQLite can do so internally (`pragma
-threads <https://www.sqlite.org/pragma.html#pragma_threads>`__)
-such as for sorting.  You can get concurrency with multiple connections.
+threads <https://www.sqlite.org/pragma.html#pragma_threads>`__) such
+as for sorting.  You can get concurrency with multiple connections.
 
 SQLite is inherently synchronous due to being written in C and using
 the C stack.
@@ -31,9 +33,9 @@ GIL (usual operation)
     second), with the operating system scheduler choosing which thread
     runs next.
 
-    The GIL can be released by C code when not using Python data structures
-    to allow other threads to run.  This is done during I/O operations
-    etc.
+    The GIL can be released by C code when not using Python data
+    structures to allow other threads Python to run.  This is done
+    during I/O and database operations etc.
 
 Free threaded (Python 3.14+)
 
@@ -43,7 +45,8 @@ Free threaded (Python 3.14+)
     not using the same objects.
 
     The extra locking can result in around a 50% performance hit
-    versus the single global lock in a single thread.
+    versus the single global lock in a single thread.  The operating
+    system scheduler can run all the threads at the same time.
 
 Async
 
@@ -58,6 +61,10 @@ Async
     hit to throughput, but latencies and time to complete are
     far more uniform.
 
+    An async framework like :mod:`asyncio` or `trio
+    <https://trio.readthedocs.io>`__ runs the event loop and chooses
+    which code to run next.
+
 How APSW works
 --------------
 
@@ -126,11 +133,11 @@ async mode or not, and behave appropriately.  You can use
 :attr:`Connection.is_async` to check.
 
 However to make type checkers and IDEs work better, the type stubs
-included with APSW have those classes so it is clear when returned
-values are direct, or need to be awaited.
+included with APSW have those synthetic classes so it is clear when
+returned values are direct, or need to be awaited.
 
-You can use :meth:`Connection.async_run` to run functions in the
-async Connection worker thread.
+You can use :meth:`Connection.async_run` to run your own functions in
+the async Connection worker thread.
 
 .. _anyio_note:
 
@@ -249,29 +256,22 @@ Async object
 Close
 !!!!!
 
-Sync object
-    Closes this object, releasing its held resources.  It is safe to
-    call close multiple times.  When you call close on a
-    :class:`Connection`, then it will close all the corresponding
-    objects like :class:`Cursor`, :class:`Blob`, :class:`Session` etc.
-
-Async object
-    You should :code:`await` calling :code:`aclose` - the async
-    version of close.  It is safe to call multiple times.  It will
-    only be effective if the event loop is still running.
-    :func:`contextlib.aclosing` is a handy context manager.
+You can call close on sync **and** async objects. When you call close on a
+:class:`Connection`, then it will close all the corresponding
+objects like :class:`Cursor`, :class:`Blob`, :class:`Session` etc.
 
-    This is important for the :class:`Connection` because the worker
-    thread will not exit until the connection is closed.  It will be
-    closed if normal garbage collection happens, but it is very easy
-    to have a stray reference preventing that.
+It is safe to call :code:`close` and :code:`aclose` multiple times,
+even on already closed objects.`
 
-    It is allowed to call :code:`close` on async objects, which will
-    immediately close them and return :exc:`ConnectionClosedError` to
-    any subsequent calls made.  This is also the only way to close an
-    object after the event loop has finished.  You can use
-    :func:`apsw.connections` to get the currently open connections.
+Sync object
+    :code:`close` closes this object in the foreground, releasing its
+    held resources.
 
+Async object
+    :code:`aclose` closes this object in the background.  You should
+    :code:`await` calling :code:`aclose` to know when it has
+    completed.  :code:`close` will close it in the foreground
+    which could take some time.
 
 Callbacks
 =========
@@ -339,8 +339,8 @@ Most configuration uses :mod:`contextvars`.
 
 :attr:`apsw.aio.deadline`
 
-    When SQLite queries or async callbacks should timeout.  (|trio|
-    and |anyio|) native timeout is also supported.
+    When SQLite queries or async callbacks should timeout.  |trio|
+    and |anyio|) native timeouts are also supported.
 
 :attr:`apsw.async_controller`
 
@@ -392,7 +392,7 @@ The controller is responsible for:
 * Sending calls from the event loop to the worker thread with
   awaitable results
 * Checking deadlines and cancellations
-* Running coroutines in the event loop, and providing their results
+* Forwarding coroutines in the event loop, and providing their results
 * Stopping the worker thread when told about database close
 
 Although it seems like a lot, they are around 50 lines of code, and
@@ -411,12 +411,13 @@ Extensions
 
 Session
 
-    You will need to use :func:`apsw.aio.make_session`
+    You should use :func:`apsw.aio.make_session` to make a
+    :class:`Session` in async mode.
 
 :class:`apsw.fts5.Table`
 
     Virtually every method and property needs to access the database.
-    Therefore you will need to run all of them in the database thread
+    Therefore you should run all of them in the database thread
     using :meth:`Connection.async_run`
 
     .. code-block:: python
@@ -497,9 +498,7 @@ CpuTotal / CpuEvtLoop / CpuDbWorker
     database worker thread.
 
 The results show that what is used only matters if you are doing very
-large numbers of calls because of very small row batch sizes.  APSW
-has to allocate space for results, so increasing the prefetch size
-results in more memory consumption and more CPU time to allocate it.
+large numbers of calls because of very small row batch sizes.
 
 .. csv-table:: Benchmark Results
     :widths: auto

src/apswtypes.py

@@ -201,7 +201,7 @@ def configure(self, connection: Connection):
         ...
 
     async def send(self, call: Callable[[], Any]) -> Any:
-        """Called from outside the worker thread to send to worker thread
+        """Called from outside the worker thread to send call to worker thread
 
         This should be async or return an awaitable, and forward
         ``call`` to the worker thread where it is called with no