"""

Caches that can freeze when the annotator needs it.

"""

#

# _freeze_() protocol:

# user-defined classes can define a method _freeze_(), which

# is called when a prebuilt instance is found. If the method

# returns True, the instance is considered immutable and becomes

# a SomePBC(). Otherwise it's just SomeInstance(). The method

# should force away any laziness that remains in the instance.

#

# Cache class:

# a cache meant to map a finite number of keys to values.

# It is normally extended lazily, until it contains all possible

# keys. The _annspecialcase_ attribute of the getorbuild() method

# forces the annotator to decode the argument's annotations,

# which must be constants or SomePBCs, actually call the

# method with all possible combinations, and gather the results.

# The idea is to completely fill the cache at annotation-time,

# using the information collected by the annotator itself about

# what the keys can actually be.

#

# Cache must be subclassed, and a _build() method provided.

# Be sure to call the parent __init__() if you override it.

#

try:

from threading import RLock

lock = RLock() # multithreading protection

except ImportError:

lock = None

class Cache(object):

def __init__(self):

self.content = {}

self._building = {}

def getorbuild(self, key):

if lock: lock.acquire()

try:

try:

return self.content[key]

except KeyError:

if key in self._building:

raise RuntimeError("%s recursive building of %r" %

(self, key))

self._building[key] = True

try:

result = self._build(key)

self.content[key] = result

finally:

del self._building[key]

self._ready(result)

return result

finally:

if lock: lock.release()

getorbuild._annspecialcase_ = "specialize:memo"

def __repr__(self):

return "<Cache %r (%i items)>" % (self.__class__.__name__, len(self.content))

def _ready(self, result):

pass

def _freeze_(self):

# needs to be SomePBC, but otherwise we can't really freeze the

# cache because more getorbuild() calls might be discovered later

# during annotation.

return True