Atomic Cache Counter Service

Design a small service that uses a memcached client to keep integer counters with atomic updates. All mutations must rely on the client's atomic counter operations rather than manual read/modify/write sequences.

Capabilities

Increment initializes and accumulates

• Incrementing a missing counter with key "page:home" by 1 returns 1 and stores the counter using the default TTL. @test
• A subsequent increment of the same key by 4 returns 5, reflecting accumulated state. @test

Decrement with zero floor

• With a counter at 3, decrementing by 1 returns 2, and decrementing by 5 afterwards returns 0 while never allowing negative values. @test

Custom deltas and reads

• Adjusting a counter by a custom positive delta updates the value accordingly, and a custom negative delta reduces it without going below zero; get_count returns the current value or a provided default when missing. @test

Bulk bumps

• Providing a mapping of keys to deltas updates each counter atomically (initializing missing counters from zero) and returns the new counts per key. @test

Implementation

@generates

API

class CounterService:
    def __init__(self, client, default_ttl: int = 0):
        """client is a configured pylibmc client; default_ttl applies when a counter is first created."""

    def increment(self, key: str, delta: int = 1) -> int:
        """Atomically increases a counter by delta, initializing missing counters at zero before the operation. Returns the new count."""

    def decrement(self, key: str, delta: int = 1) -> int:
        """Atomically decreases a counter by delta without going below zero. Returns the new count."""

    def bulk_bump(self, deltas: dict[str, int]) -> dict[str, int]:
        """Atomically adjusts multiple counters by given deltas (positive to increment, negative to decrement). Returns updated counts keyed by counter name."""

    def get_count(self, key: str, default: int = 0) -> int:
        """Fetches the current counter value, returning the provided default when the counter does not exist."""

Dependencies { .dependencies }

pylibmc { .dependency }

Memcached client used to persist counters with atomic increment/decrement support.