'Try to allocate an item of ItemClass type.
I expect this to work in all cases because I expect the pool size to be
large enough for any situation.  Nonetheless, there is some defensive
programming in here.
Since the allocations are persisted, there is the chance to leak
allocations which should have been released but were not.  This leak
could eventually exhaust the pool.
So, if a new allocation is needed, the code first checks to see if
there are any remembered allocations for the key.  If not, it checks
the free pool.  If the free pool is empty then it dumps the remembered
allocations to free the pool.  This final desperate step will not
happen often in practice.'

def allocate(self, key):

    entry = self.lookup(key)
    if entry:
        return entry
    if (not self.pool):
        self.pool.update(self.remembered.values())
        self.remembered.clear()
        if (not self.pool):
            raise RuntimeError(('Cannot    allocate    item    of    type:    %s    from    pool    using    file    %s' % (self.ItemClass, self.state_file)))
    self.allocations[key] = self.pool.pop()
    self._write_allocations()
    return self.allocations[key]
