gnome.utilities.cache
=====================

.. py:module:: gnome.utilities.cache

.. autoapi-nested-parse::

   cache system for caching element data on disk for
   accessing again for output, etc.



Attributes
----------

.. autoapisummary::

   gnome.utilities.cache.global_cache_dir


Exceptions
----------

.. autoapisummary::

   gnome.utilities.cache.CacheError


Classes
-------

.. autoapisummary::

   gnome.utilities.cache.ElementCache


Functions
---------

.. autoapisummary::

   gnome.utilities.cache.clean_up_cache


Module Contents
---------------

.. py:data:: global_cache_dir

.. py:exception:: CacheError

   Bases: :py:obj:`Exception`


   Here so we can be sure the user knows the error is coming from here

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: clean_up_cache(dir_name=global_cache_dir)

   Deletes a cache dir.

   Designed to be called at program exit. and/or when
   individual cache objects are deleted

   raises a warning if there is problem deleting a particular directory


.. py:class:: ElementCache(cache_dir=None, enabled=True)

   Cache for element data -- i.e. the data associated with the particles.
   This caches UncertainSpillContainerPair
   The cache can be accessed to re-draw the LE movies, etc.

   TODO: This is a really fragile module in terms of handling multiple
         instances.  The __del__() method of previous instances can clear
         the _cache_dir at the whim of the GC.
         We may want to manage this differently.

   initialize a new cache object

   :param cache_dir=None: full path to the directory where the cache
                          should be stored.
                          If not provided, a temp dir will be created by
                          the python tempfile module


   .. py:attribute:: recent


   .. py:attribute:: enabled
      :value: True



   .. py:attribute:: lock


   .. py:method:: save_timestep(step_num, spill_container_pair)

      add a time step of data to the cache

      :param step_num: the step number of the data
      :param spill_container: the spill container at this step



   .. py:method:: load_timestep(step_num)

      Returns a SpillContainer with the data arrays cached on disk

      :param step_num: the step number you want to load.



   .. py:method:: rewind()

      Rewinds the cache -- clearing out everything