PageRenderTime 10ms CodeModel.GetById 2ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/src/yolk-cache-string_keys.ads

http://github.com/ThomasLocke/yolk
Ada | 110 lines | 24 code | 15 blank | 71 comment | 0 complexity | 960a2d0ffc1fdd61c24f8413037546a9 MD5 | raw file
  1-------------------------------------------------------------------------------
  2--                                                                           --
  3--                   Copyright (C) 2010-, Thomas Løcke                   --
  4--                                                                           --
  5--  This library is free software;  you can redistribute it and/or modify    --
  6--  it under terms of the  GNU General Public License  as published by the   --
  7--  Free Software  Foundation;  either version 3,  or (at your  option) any  --
  8--  later version. This library is distributed in the hope that it will be   --
  9--  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of  --
 10--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                     --
 11--                                                                           --
 12--  As a special exception under Section 7 of GPL version 3, you are         --
 13--  granted additional permissions described in the GCC Runtime Library      --
 14--  Exception, version 3.1, as published by the Free Software Foundation.    --
 15--                                                                           --
 16--  You should have received a copy of the GNU General Public License and    --
 17--  a copy of the GCC Runtime Library Exception along with this program;     --
 18--  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
 19--  <http://www.gnu.org/licenses/>.                                          --
 20--                                                                           --
 21-------------------------------------------------------------------------------
 22
 23--  A simple and fairly dumb cache.
 24--  In order for an element to be valid, it must:
 25--
 26--    1. have been added to the cache using the Write procedure
 27--    2. be younger than Max_Element_Age
 28--
 29--  WARNING!
 30--    As opposed to the Discrete_Keys cache, which maximum size is known at all
 31--    times, the String_Keys cache carries the risk of growing until there are
 32--    no more resources available.
 33--    Either let the cache automatically clean itself (Cleanup_Size and
 34--    Cleanup_On_Write) or do it manually by calling Cleanup/Clear whenever you
 35--    decide it is necessary.
 36--
 37--  Note that whenever an invalid element is found by the Read procedure,
 38--  (Is_Valid = False), it is automatically deleted from the cache.
 39
 40generic
 41
 42   type Element_Type is private;
 43   Cleanup_Size : Positive := 200;
 44   --  Call the Cleanup procedure when the cache contains >= Cleanup_Size
 45   --  elements. The Cleanup procedure first tries to delete elements that are
 46   --  older than Max_Element_Age, and if that doesn't bring the amount of
 47   --  cached elements below Cleanup_Size, then elements are simply _randomly_
 48   --  deleted until the size is 1 lower than Cleanup_Size.
 49   --  Obviously it makes little sense to set this number below the value of
 50   --  Reserved_Capacity.
 51
 52   Cleanup_On_Write : Boolean := True;
 53   --  Call the Cleanup procedure when Write is called and the size of the
 54   --  cache is >= Cleanup_Size. If Cleanup_On_Write is False, Cleanup is not
 55   --  called automatically, and you'll have to manage the size of the cache
 56   --  manually.
 57
 58   Max_Element_Age : Duration := 3600.0;
 59   ---  Elements that are older than Max_Element_Age are considered invalid.
 60
 61   Reserved_Capacity : Positive := 100;
 62   --  Set this as close as possible to the expected final size of the cache.
 63   --  Setting it too low will result in a performance-loss whenever the
 64   --  hashed map has to be resized because new key/value pairs are added.
 65   --  Setting it too high will result in wasted resources.
 66   --  This setting has NO bearing on the actual size of the cache. The cache
 67   --  will happily grow beyond the Reserved_Capacity.
 68
 69package Yolk.Cache.String_Keys is
 70
 71   procedure Cleanup;
 72   --  If the cache size is >= Cleanup_Size, then delete all elements where age
 73   --  is older than Max_Element_Age. If this doesn't bring the size of the
 74   --  cache down below Cleanup_Size, then elements are deleted _randomly_,
 75   --  until the size is Cleanup_Size - 1.
 76   --  Cleanup is called automatically if Cleanup_On_Write is True.
 77
 78   procedure Clear;
 79   --  Clear the entire cache.
 80
 81   procedure Clear
 82     (Key : in String);
 83   --  Remove the currently cached element associated with Key.
 84
 85   function Is_Valid
 86     (Key : in String)
 87      return Boolean;
 88   --  Return True if the element associated with Key exists and is younger
 89   --  than Max_Element_Age.
 90
 91   function Length
 92     return Natural;
 93   --  Return the amount of elements currently in the cache. This counts both
 94   --  valid and invalid elements.
 95
 96   procedure Read
 97     (Key      : in  String;
 98      Is_Valid : out Boolean;
 99      Value    : out Element_Type);
100   --  Fetch the element associated with Key.
101   --
102   --  WARNING!
103   --    Value will contain undefined garbage if Is_Valid is False.
104
105   procedure Write
106     (Key   : in String;
107      Value : in Element_Type);
108   --  Add Value to the cache, and associate it with Key.
109
110end Yolk.Cache.String_Keys;