txt: ## dist_cpan-ATROXAPER-Propius.md
  [![Build Status](https://travis-ci.org/atroxaper/p6-Propius.svg?branch=master)](https://travis-ci.org/atroxaper/p6-Propius)
  
  # Propius
  
  Memory cache with loader and eviction by time.
  Inspired by [Guava's CacheLoader](https://github.com/google/guava/wiki/CachesExplained).
  
  ## Examples
  
  ```
      use Propius;
      my $cache = eviction-based-cache(
        loader => { $:key ** 2 }, # calculation of the new value for key
        removal-listener => { say 'removed ', $:key, ':', $:value, ' cause ', $:cause },
          # optional listener for removed values
        expire-after-write => 60); # freshness time of cached values;
      
      $cache.get(5); # returns prodused the new value - 25;
      $cache.get(5): # returns cached value - 25;
      $cache.get-if-exists(6); # returns Any
      $cache.put(:9key, loader => { $:key ** 3 }); # cache value for specified loader
      $cache.get(9); # returns cached value - 729
      # ... 60 seconds later in output (in case you use the cache)
      removed 5:25 cause Expired
      removed 9:729 cause Expired
  
  ```
  
  ## Create
  
  You can use sub `eviction-based-cache` for creation the new cache.
  Arguments are:
  
  `:&loader! where .signature ~~ :(:$key)` - sub with signature like `(:$key)`.
  The sub will be used for producing the new values. Obligatory argument.
  
  `:&removal-listener where .signature ~~ :(:$key, :$value, :$cause)` -
  sub with signature like `(:$key, :$value, :$cause)`.
  The sub will be called in case when value removed from the cache.
  Cause is element of enum `RemoveCause`.
  
  `:$expire-after-write` - how long the cache have to store value after its last re/write
  
  `:$expire-after-access` - how long the cache have to store value after its last access (read or write)
  
  `:$time-unit` - object of `TimeUnit`, indicate time unit of expire-after-write/access value.
  Seconds by default.
  
  `:$ticker` - object of `Ticker`, witch is used for retrieve 'current' time.
  Can be specified for overriding standard behaviour (current system time), for example for testing.
  
  `:$size` - max capacity of the cache.
  
  ## Notes
  
  The cache can use object keys. If you want that you have to control .WHICH method of keys.
  
  Of course the cache is thread-save. It simply uses OO::Monitors for synchronisation.
  
  ## Available methods
  
  ### get(Any:D $key)
  
  Retrieve value by key.
  
  ```
      my $is-primitive = $cache.get(655360001);
  
  ```
  
  If there is no value for specified key then loader with be
  used to produce the new value.
  
  ### get-if-exists(Any:D $key)
  
  Retrieve value by key only if it exists.
  
  ```
      my $is-primitive = $cache.get-if-exists(900900900900990990990991);
  
  ```
  
  If there is no value for specified key then Any will be returned.
  
  ### put(Any:D :$key, Any:D :$value)
  
  ### put(Any:D :$key, :&loader! where .signature ~~ :(:$key))
  
  Store a value in cache with/without specified loader.
  
  ```
      $cache.put(:900900900900990990990991key, :value);
      $cache.put(:2key, loader => { True });
  
  ```
  
  It will rewrite any cached value for specified key. In that case
  removal-listener will be called with old value cause Replaced.
  
  In case of cache already reached max capacity value which has not
  been used for a longest time will be removed. In that case
  removal-listener will be called with old value cause Size.
  
  ### invalidate
  
  ### invalidateAll(List:D @keys)
  
  ### invalidateAll
  
  Mark value/values for specified/all key/keys as invalidate.
  
  ```
      $cache.invalidate(655360001);
      $cache.invalidateAll(<1 2 3>);
      $cahce.invalidateAll();
  
  ```
  
  The value will be removed and removal-listener will be called for each
  old values cause Explicit.
  
  ### elems
  
  Return keys and values stored in cache as Hash.
  
  ```
      $cache.elems();
  
  ```
  
  ### hash
  
  Return keys and values stored in cache as Hash.
  
  ```
      $cache.hash();
  
  ```
  
  This is a copy of values. Any modification of returned cache will no have
  an effect on values in the store.
  
  ### clean-up
  
  Clean evicted values from cache.
  
  ```
      $cache.clean-up();
  
  ```
  
  This method may be invoked directly by user.
  
  The method invoked on each write operation and ones for several read operation
  if there was no write operation recently.
  
  It means that evicted values will not be removed on just in time of its eviction.
  This is done for the purpose of optimisation - is it not requires special thread
  for checking an eviction. If it is issue for you then you can call it method yourself
  by some scheduled Promise for example.
  
  ## Sources
  
  [GitHub](https://github.com/atroxaper/p6-Propius)
  
  ## Author
  
  Mikhail Khorkov [atroxaper@cpan.org](mailto:atroxaper@cpan.org)
  
  ## License
  
  See <LICENSE> file for the details of the license of the code in this repository.
  