DBLock Context Manager

The Single Writer Locking Problem

We can use the fcntl module to lock files. This module (and the Linux OS) offers exclusive locks and shared locks.

(For Windows folks, get a package like portalocker or use the functions in pywin32.)

The objectives are these:

• Take out an exclusive lock for transactions that will update the database.
• Take out a shared lock for transactions that read the database.

This Shared vs. Exclusive locking is elegant, but also habors a small problem.

Consider a web server. Each GET transaction acquires a shared lock, reads the data, prepares the response, and releases the shared lock. Because the shared lock prevents a writer from getting an exclusive lock, the data is untouched for the duration of the transaction. There's no possibility of data file corruption mid-transaction because of a concurrent write.

Each POST/PUT/PATCH/DELETE transaction acquires an exclusive lock, reads and writes the data, prepares a response, and releases the exclusive lock. This forces the writer to wait for readers to finish. It prevents any reader from seeing incomplete or uncreadable files.

The underlying dbm file is updated in one smooth, atomic event. Everyone sees the data in a consistent state at all times.

Yes, it's coarse-grained whole-database level locking. The point was to avoid the overheads of a huge SQL server. A RESTful service can read and write local files. Emphasis on the read. Why have a super-elaborate database server to provide rows and tables that have to be assembled into JSON documents? Maybe just read the JSON document from the database and reply with it.

But.

There's a problem: a parade of readers can prevent the writer from getting in.

And so it goes: a sequence of overlapping readers will starve the writer. This is called Livelock, and — while rare — it’s not impossible.

Preventing Livelock

One algorithm for preventing livelock is to have a “pending writer queue” that the readers have to acknowledge.

Think of a velvet rope to get into the most exclusive club in town.

The writer talks to the bouncer, and the line of readers is stopped. No one gets in. Once the club is empty of readers, the writer is allowed in and has the place to themself. When they’re done writing, then they’re out of there, so the readers can crowd the place again.

This is sometimes called the “preferred writer” solution. It’s unfair by design because many web requests are read requests; write requests are less common. Overall performance depends on getting any write out of the way as soon as possible. There are other variants that are more equitable, but also a bit more complicated.

To prevent livelock, we need some kind of shared queue to broadcast to all concurrent processes that there’s a writer waiting.

We can do this using two lock files:

• A “queue” lock. This is always Exclusive. It's always acquired first. In effect, it's a one-element queue.
• The “working” lock. The working lock is either Shared or Exclusive.

The queue lock defines a mutual exclusion zone of code (called a mutex) where at most one process is able to run. The idea is readers enter the mutex, get their shared working lock, and leave the mutex. Once they have their shared lock, they can loiter, doing whatever it is they need to do.

When a writer enters the mutex, they have to wait for their exclusive working lock before they leave the mutex. This stops the readers.

Here are some play-by-play views for a number of scenarios.

Python Implementation

This is intended to be used with Flask.

from pathlib import Path
from flask import Flask

class DBLock:

    def __init__(self, app: Flask | None = None) -> None:
        if app:
            self.init_app(app)

    def init_app(self, app: Flask) -> None:
        self.lock_path = Path(cast(str, app.config.get("DB_LOCK_FILENAME", "dblock")))
        self.queue_path = self.lock_path.with_suffix(".dbqueue")
        self.thread_local = threading.local()

This could be refactored to work outside a Flask-specific context.

The thread_local storage is required to track each thread's unique open file handles.

The essence is acquiring a lock and releaing a lock. The "lock mode" is one the fcntl.LOCK_EX or fcntl.LOCK_SH values.

def acquire(self, lock_mode: int) -> Self:
    if "lock_file" not in self.thread_local.__dict__:
        # Enter Queue Mutex to acquire a database lock.
        queue_file = self.queue_path.open("w+")
        fcntl.flock(queue_file, fcntl.LOCK_EX)
        self.thread_local.lock_file = self.lock_path.open("w+")
        fcntl.flock(self.thread_local.lock_file, lock_mode)
        # Exit Queue Mutex. Permits another thread (or process) to acquire a lock.
        fcntl.flock(queue_file, fcntl.LOCK_UN)
    return self

def release(self) -> None:
    if "lock_file" in self.thread_local.__dict__:
        fcntl.flock(self.thread_local.lock_file, fcntl.LOCK_UN)
        self.thread_local.lock_file.close()
        delattr(self.thread_local, "lock_file")

The acquire and release are the algorithm described above. An exclusive lock defines a system-wide Mutex for all threads and processes. The working lock is either shared or exclusive.

The cleanup on release undoes the lock, closes the file to release any OS resources, and also purges the thread_local to make sure there's no confusion about the state.

Some useful overheads:

close = release

def is_locked(self) -> bool:
    # print(f"is_locked: {self.thread_local.__dict__=}")
    return "lock_file" in self.thread_local.__dict__

If we provide a close() method, then the contextlib.closing() context manager can be used.

The is_locked() method can be helpful to know the state of the lock. It's far better to use the with statement to define a context that eliminates any doubt.

While this can be used with contextlib functions, it seems helpful to provide explicit context management.

def __enter__(self) -> Self:
    return self

def __exit__(
    self,
    exc_type: type[Exception],
    exc_val: Exception,
    exc_tb: TracebackException,
) -> Literal[False]:
    self.release()
    return False

And. Two convenience methods to avoid having to muck around with fcntl.LOCK_SH and fcntl.LOCK_EX.

def shared(self) -> Self:
    """
    Context manager, equivalent to::

        with dblock.acquire(fcntl.LOCK_SH):
            pass
    """
    self.acquire(fcntl.LOCK_SH)
    return self

def exclusive(self) -> Self:
    """
    Context manager, equivalent to::

        with dblock.acquire(fcntl.LOCK_EX):
            pass
    """
    self.acquire(fcntl.LOCK_EX)
    return self

The goal is to have relatively lightweight code like the following.

Some Flask app setup:

dblock = DBLock()
dblock.init_app(app)

Within a GET view function:

with dblock.shared():
    with dbm.open(some_file) as db:
        item = SomeClass.model_validate_json(db[your_key_here])

Within a POST/PUT/PATCH/DELETE view function:

with dblock.exclusive():
    with dbm.open(some_file, flag='c') as db:
        db[item.id] = item.model_dump_json().encode('utf-8')

By acquiring an exclusive access lock, all changes will be saved reliably and predictably: an atomic state change.

And yes, the explicit model_validate_json() and model_dump_json() is wordy. I use a DB class to conceals these details.

Conclusion

We can use dbm as a dictionary-like repository of objects serialized as JSON.

We have the benefits of a fancy relational database without the overheads.