StumbleCache is a mmap backed caching extension for PHP
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


  • MMAP based file backed
  • Fixed allocations ie. 500k 2k cache blocks
  • No gc, if we see a url once in will most likely be used again so just let it keep that storage block, we would likely clear the entire cache every x days
  • Minimal locking - keep stats per process, block based locking if needed
  • make things very configurable, so we can have multiple caches per machine, user specified # blocks, size etc


  • like store and fetch, update
  • with cache configured from userland
  • per datatype: user records, url id,
  • so expiry on a ttl, and the client can also update a specific entry
  • each item has a specific ttl
  • statistics: qps and hitrate
    • write at end of process, doesn't matter if they are out of date
    • just for monitoring
  • 64bit linux
  • url id is 64bit
  • data is just a variable
  • igbinary or php serialisation


  • stumblecache.location: the path where all the caches are stored

Class: StumbleCacheOptions

__construct( nrOfItems, itemSize )

  • nrOfItems is the maximum number of items in the cache.

  • itemSize is the size of each item in the cache.

    rounded up to nearest 4kb (or pagesize)

The cache will use nrOfItems * itemSize amount of memory, plus some overhead.

Class: StumbleCache

__construct ( cacheRef )

  • cacheRef: string: name of the cache

Cache Layout



page 0: meta-data

  • cache file version: 4 bytes
  • item size: 4 bytes
  • nr of items: 4 bytes
  • next data page: 4 bytes

page 1-x: index, b-tree

  • b-tree node: 1023 keys, 1024 children

    • header:

      • leaf: yes/no byte
      • nrOfKeys: 1-1023 2 bytes
    • keys

      • key: 8 bytes

      • value idx: 4 bytes number = idx into data block

      • expire ts: 2 bytes

      • flags: 2 bytes

        • in use: 1 bit