Class Cache

Caching proxy for object retrieval and caching.

Object factories ("fetchers") are registered in the `Cache` object and used
to e.g. retrieve requested objects from network.  They are called only when
the requested object is not in the cache or is not fresh enough.

A state (freshness level) name may be provided when requesting an object.
When the cached item state is "less fresh" then requested, then new object
will be retrieved.

Following states are defined:

  - 'new': always a new object should be retrieved.
  - 'fresh': a fresh object (not older than freshness time)
  - 'old': object not fresh, but most probably still valid.
  - 'stale': object known to be expired.

:Ivariables:
    - `default_freshness_period`: default freshness period (in seconds).
    - `default_expiration_period`: default expiration period (in seconds).
    - `default_purge_period`: default purge period (in seconds). When
      0 then items are never purged because of their age.
    - `max_items`: maximum number of items to store.
    - `_items`: dictionary of stored items.
    - `_items_list`: list of stored items with the most suitable for
      purging first.
    - `_fetcher`: fetcher class for this cache.
    - `_active_fetchers`: list of active fetchers sorted by the time of
      its expiration time.
    - `_lock`: lock for thread safety.
:Types:
    - `default_freshness_period`: timedelta
    - `default_expiration_period`: timedelta
    - `default_purge_period`: timedelta
    - `max_items`: `int`
    - `_items`: `dict` of (`classobj`, addr) -> `CacheItem`
    - `_items_list`: `list` of (`int`, `datetime`, `CacheItem`)
    - `_fetcher`: `CacheFetcher` based class
    - `_active_fetchers`: `list` of (`int`, `CacheFetcher`)
    - `_lock`: `threading.RLock`

Initialize a `Cache` object.

:Parameters:
    - `default_freshness_period`: default freshness period (in seconds).
    - `default_expiration_period`: default expiration period (in seconds).
    - `default_purge_period`: default purge period (in seconds). When
      0 then items are never purged because of their age.
    - `max_items`: maximum number of items to store.
:Types:
    - `default_freshness_period`: number
    - `default_expiration_period`: number
    - `default_purge_period`: number
    - `max_items`: number

Add an item to the cache.

Item state is updated before adding it (it will not be 'new' any more).

:Parameters:
    - `item`: the item to add.
:Types:
    - `item`: `CacheItem`

:return: state of the item after addition.
:returntype: `str`

Get an item from the cache.

:Parameters:
    - `address`: its address.
    - `state`: the worst state that is acceptable.
:Types:
    - `address`: any hashable
    - `state`: `str`

:return: the item or `None` if it was not found.
:returntype: `CacheItem`

Force cache item state change (to 'worse' state only).

:Parameters:
    - `state`: the new state requested.
:Types:
    - `state`: `str`

Get the number of items in the cache.

:return: number of items.
:returntype: `int`

Remove purged and overlimit items from the cache.

TODO: optimize somehow.

Leave no more than 75% of `self.max_items` items in the cache.

Remove a running fetcher from the list of active fetchers.

:Parameters:
    - `fetcher`: fetcher instance.
:Types:
    - `fetcher`: `CacheFetcher`

Request an object with given address and state not worse than
`state`. The object will be taken from cache if available, and
created/fetched otherwise. The request is asynchronous -- this metod
doesn't return the object directly, but the `object_handler` is called
as soon as the object is available (this may be before `request_object`
returns and may happen in other thread). On error the `error_handler`
will be called, and on timeout -- the `timeout_handler`.

:Parameters:
    - `address`: address of the object requested.
    - `state`: the worst acceptable object state. When 'new' then always
      a new object will be created/fetched. 'stale' will select any
      item available in cache.
    - `object_handler`: function to be called when object is available.
      It will be called with the following arguments: address, object
      and its state.
    - `error_handler`: function to be called on object retrieval error.
      It will be called with two arguments: requested address and
      additional error information (fetcher-specific, may be
      StanzaError for XMPP objects).  If not given, then the object
      handler will be called with object set to `None` and state
      "error".
    - `timeout_handler`: function to be called on object retrieval
      timeout.  It will be called with only one argument: the requested
      address. If not given, then the `error_handler` will be called
      instead, with error details set to `None`.
    - `backup_state`: when set and object in state `state` is not
      available in the cache and object retrieval failed then object
      with this state will also be looked-up in the cache and provided
      if available.
    - `timeout`: time interval after which retrieval of the object
      should be given up.
    - `freshness_period`: time interval after which the item created
      should become 'old'.
    - `expiration_period`: time interval after which the item created
      should become 'stale'.
    - `purge_period`: time interval after which the item created
      shuld be removed from the cache.
:Types:
    - `address`: any hashable
    - `state`: "new", "fresh", "old" or "stale"
    - `object_handler`: callable(address, value, state)
    - `error_handler`: callable(address, error_data)
    - `timeout_handler`: callable(address)
    - `backup_state`: "new", "fresh", "old" or "stale"
    - `timeout`: `timedelta`
    - `freshness_period`: `timedelta`
    - `expiration_period`: `timedelta`
    - `purge_period`: `timedelta`

Set the fetcher class.

:Parameters:
    - `fetcher_class`: the fetcher class.
:Types:
    - `fetcher_class`: `CacheFetcher` based class

Do the regular cache maintenance.

Must be called from time to time for timeouts and cache old items
purging to work.

Update state of an item in the cache.

Update item's state and remove the item from the cache
if its new state is 'purged'

:Parameters:
    - `item`: item to update.
:Types:
    - `item`: `CacheItem`

:return: new state of the item.
:returntype: `str`