[gaborbernat]

With the default is_singleton=True, every AsyncReadWriteLock and AsyncSoftReadWriteLock on a path is a wrapper around one shared sync lock. All such wrappers also share one task table (the record of which asyncio task holds the lock and how many times), the model #746 introduced. Three paths left that table believing in holds the sync lock no longer had. Tasks then ran read_lock() or write_lock() bodies while another process held the write lock. 🔓 This PR makes close() end only the holds taken through the closing wrapper, and makes the table ask the sync lock before it lets a task join an existing hold.

Closing one wrapper ended every wrapper's hold

AsyncReadWriteLock.close() ran ReadWriteLock.close() on the shared sync lock and then reset the shared table. The sync close() documents that it ends every thread's hold on this instance. So a program that builds one wrapper per request and closes it in a finally, as the async read / write how-to shows, lost its lock when any request finished. A task still inside async with rw.write_lock() through another wrapper kept running while another process acquired the write lock. A synchronous ReadWriteLock user of the same path lost its hold the same way. The holder learned of it only when its own release raised RuntimeError. AsyncSoftReadWriteLock.close() had the same two steps. The behavior dates from #506, which added the class.

sequenceDiagram
    participant T1 as task 1 (wrapper A)
    participant T2 as task 2 (wrapper B)
    participant L as shared ReadWriteLock
    participant P as another process
    T1->>L: acquire_write()
    rect rgb(255, 214, 214)
        Note over T2,L: before this PR
        T2->>L: close()  (rollback, close connection)
        P->>L: acquire_write()
        L-->>P: granted while task 1 is still inside
    end
    rect rgb(216, 243, 220)
        Note over T2,L: after this PR
        T2->>L: close() drops only wrapper B's holds
        P->>L: acquire_write(blocking=False)
        L-->>P: Timeout
    end

Loading

Each task's hold now records its nesting count per wrapper it took a level through, in _TaskHold. A wrapper's close() ends only the levels a task took through that wrapper, and the task's hold ends with its last level. close() retires those holds through _TaskOwners.retire(). The wrapper gives back the sync lock's level (its count of nested acquisitions) only when no other hold remains. A wrapper built with is_singleton=False owns its sync lock and still closes it. The trade-off: a singleton wrapper no longer closes the SQLite connection itself. The sync lock closes it when the last level goes, as it already did for release().

A reader arriving during close() joined the ending hold

close() awaited its executor call with the wrapper's closed flag still unset and the table still showing a read hold. A task that called acquire_read() in that window, about 0.2 ms per close, joined the hold without any sync-lock call. It entered its read_lock() body with no SQLite transaction behind it. A service closing its lock under load met this on most shutdowns. The window came in with the per-task table in #746.

sequenceDiagram
    participant C as closing task
    participant R as arriving reader
    participant T as task table
    participant B as sync lock
    C->>T: close(): mark closed, drop its holds
    rect rgb(207, 228, 255)
        Note over T: transitioning: joins wait
        C->>B: release the level (executor)
        R->>T: acquire_read()
        T-->>R: wait
        B-->>C: done
        C->>T: finish transition
    end
    T-->>R: enter
    R->>R: closed wrapper raises#59; other wrapper takes the lock

Loading

The closing wrapper now sets its closed flag before any await, so it refuses later acquires. The retirement runs as a table transition: arrivals wait instead of joining, including a reader already queued behind a writer. A task that waited and then enters re-checks the wrapper, so a close that landed meanwhile raises the closed-database error.

The table did not see a synchronous close() or forced release

Synchronous code can call ReadWriteLock(path).close() or release(force=True) on the singleton the async wrapper shares; the how-to's ReadWriteLock example ends with close() in a finally. The sync call ended the task's level, but the table still listed that task as a reader. Every later acquire_read() through any wrapper on the path was then answered "held" without touching the sync lock. In-process writers timed out against that phantom reader until the process exited. AsyncSoftReadWriteLock behaved the same after a synchronous SoftReadWriteLock.close().

flowchart LR
    A[acquire_read] --> Q{table shows a hold?}
    Q -- no --> E[enter sync lock]
    Q -- yes --> J{sync lock still has the tasks' level?}
    J -- yes --> H[join the hold]
    J -- no --> F[forget stale holds] --> E
    classDef ok fill:#d8f3dc,stroke:#2d6a4f,color:#1b4332;
    classDef bad fill:#ffd6d6,stroke:#c1121f,color:#5c0000;
    classDef info fill:#cfe4ff,stroke:#1f6feb,color:#0b1f3a;
    class A,Q,J info;
    class H,E ok;
    class F bad;

Loading

Before answering "held", _admit() now asks the wrapper whether the sync lock still has the level taken for the tasks, through _holds_level_of(). When it is gone, the table forgets the holds. After a sync close() the next async acquire raises sqlite3.ProgrammingError, as every other path does. After a sync forced release it takes a fresh lock. close() on a wrapper whose tasks' level sync code already ended finishes without a backend call. The check reads the sync lock's level without its internal lock: the event loop must not wait out a release running on another thread, and a stale answer is what a caller asking a moment earlier would have had.

Behavior changes

close() on a singleton wrapper no longer closes the shared ReadWriteLock or SoftReadWriteLock. Tasks holding through other wrappers and synchronous users of the same path keep their locks; the how-to says so. A non-blocking acquire that lands during a close raises Timeout, as it does during any other in-flight transition. The sync-lock check and the admission are not one atomic step. A synchronous close() that lands in the few bytecodes between them can still admit that one task into the ended hold, which close() now states.