icache.hpp
上传用户:yhdzpy8989
上传日期:2007-06-13
资源大小:13604k
文件大小:10k
源码类别:

生物技术

开发平台:

C/C++

  1. /*
  2.  * ===========================================================================
  3.  * PRODUCTION $Log: icache.hpp,v $
  4.  * PRODUCTION Revision 1000.3  2004/06/01 19:39:14  gouriano
  5.  * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.4
  6.  * PRODUCTION
  7.  * ===========================================================================
  8.  */
  9. #ifndef UTIL___ICACHE__HPP
  10. #define UTIL___ICACHE__HPP
  11. /*  $Id: icache.hpp,v 1000.3 2004/06/01 19:39:14 gouriano Exp $
  12.  * ===========================================================================
  13.  *
  14.  *                            PUBLIC DOMAIN NOTICE
  15.  *               National Center for Biotechnology Information
  16.  *
  17.  *  This software/database is a "United States Government Work" under the
  18.  *  terms of the United States Copyright Act.  It was written as part of
  19.  *  the author's official duties as a United States Government employee and
  20.  *  thus cannot be copyrighted.  This software/database is freely available
  21.  *  to the public for use. The National Library of Medicine and the U.S.
  22.  *  Government have not placed any restriction on its use or reproduction.
  23.  *
  24.  *  Although all reasonable efforts have been taken to ensure the accuracy
  25.  *  and reliability of the software and data, the NLM and the U.S.
  26.  *  Government do not and cannot warrant the performance or results that
  27.  *  may be obtained by using this software or data. The NLM and the U.S.
  28.  *  Government disclaim all warranties, express or implied, including
  29.  *  warranties of performance, merchantability or fitness for any particular
  30.  *  purpose.
  31.  *
  32.  *  Please cite the author in any work or product based on this material.
  33.  *
  34.  * ===========================================================================
  35.  *
  36.  * Authors:  Anatoliy Kuznetsov
  37.  *
  38.  * File Description: cache interface specs.
  39.  *
  40.  */
  41. /// @file icache.hpp
  42. /// Cache interface specs. 
  43. ///
  44. /// File describes interfaces used to create local cache of 
  45. /// binary large objects (BLOBS).
  46. #include <corelib/plugin_manager_impl.hpp>
  47. #include <util/reader_writer.hpp>
  48. #include <string>
  49. BEGIN_NCBI_SCOPE
  50. /// BLOB cache read/write/maintanance interface.
  51. ///
  52. /// ICache describes caching service. Any large binary object
  53. /// can be stored in cache and later retrived. Such cache is a 
  54. /// temporary storage and some objects can be purged from cache based
  55. /// on an immediate request, version or access time 
  56. /// based replacement (or another implementation specific depreciation rule).
  57. ///
  58. /// Cache elements are accesed by key-subkey pair. 
  59. /// 
  60. class ICache
  61. {
  62. public:
  63.     
  64.     /// ICache can keeps timestamps of every cache entry.
  65.     /// This enum defines the policy how it is managed.
  66.     /// Different policies can be combined by OR (|)
  67.     /// @sa SetTimeStampPolicy
  68.     enum ETimeStampPolicy {
  69.         /// Timestamp management disabled
  70.         fNoTimeStamp       = 0,
  71.         /// Cache element is created with a certain timestamp (default)
  72.         fTimeStampOnCreate = (1 << 0),
  73.         /// Timestamp is updated every on every access (read or write)
  74.         fTimeStampOnRead   = (1 << 1),
  75.         
  76.         /// Timestamp full key-subkey pair. By default only key is taken
  77.         /// into account
  78.         fTrackSubKey       = (1 << 2),
  79.         /// Expire objects older than a certain time frame
  80.         /// Example: If object is not accessed within a week it is 
  81.         ///          droped from the cache.
  82.         fExpireLeastFrequentlyUsed  = (1 << 3),
  83.         /// Expired objects should be deleted on cache mount (Open)
  84.         fPurgeOnStartup             = (1 << 4),
  85.         /// Expiration timeout is checked on any access to cache element
  86.         fCheckExpirationAlways      = (1 << 5)
  87.     };
  88.     typedef int TTimeStampFlags;
  89.     /// Set timestamp update policy
  90.     /// @param policy
  91.     ///   ORed combination of TimeStampUpdatePolicy masks.
  92.     virtual void SetTimeStampPolicy(TTimeStampFlags policy, int timeout) = 0;
  93.     /// Get timestamp policy
  94.     /// @return
  95.     ///    Timestamp policy
  96.     virtual TTimeStampFlags GetTimeStampPolicy() const = 0;
  97.     /// Get expiration timeout
  98.     /// @return
  99.     ///    Expiration timeout in seconds
  100.     /// @sa GetExpirationPolicy(), SetExpirationPolicy()
  101.     virtual int GetTimeout() = 0;
  102.     /// If to keep already cached versions of the BLOB when storing
  103.     /// another version of it (not necessarily a newer one)
  104.     /// @sa Store(), GetWriteStream()
  105.     enum EKeepVersions {
  106.         /// Do not delete other versions of cache entries
  107.         eKeepAll,
  108.         /// Delete the earlier (than the one being stored) versions of
  109.         /// the BLOB
  110.         eDropOlder,
  111.         /// Delete all versions of the BLOB, even those which are newer
  112.         /// than the one being stored
  113.         eDropAll
  114.     };
  115.     /// Set version retention policy
  116.     ///
  117.     /// @param policy
  118.     ///    Version retetion mode
  119.     virtual void SetVersionRetention(EKeepVersions policy) = 0;
  120.     /// Get version retention
  121.     virtual EKeepVersions GetVersionRetention() const = 0;
  122.     /// Add or replace BLOB
  123.     ///
  124.     /// @param key 
  125.     ///    BLOB identification key
  126.     /// @param key 
  127.     ///    BLOB identification sub-key
  128.     /// @param version 
  129.     ///    BLOB version
  130.     /// @param data 
  131.     ///    pointer on data buffer
  132.     /// @param size 
  133.     ///    data buffer size in bytes (chars)
  134.     /// @param flag 
  135.     ///    indicator to keep old BLOBs or drop it from the cache
  136.     virtual void Store(const string&  key,
  137.                        int            version,
  138.                        const string&  subkey,
  139.                        const void*    data,
  140.                        size_t         size) = 0;
  141.     /// Check if BLOB exists, return BLOB size.
  142.     ///
  143.     /// @param key 
  144.     ///    BLOB identification key
  145.     /// @param subkey
  146.     ///    BLOB identification subkey
  147.     /// @param version 
  148.     ///    BLOB version
  149.     /// @return 
  150.     ///    BLOB size or 0 if it doesn't exist or expired
  151.     virtual size_t GetSize(const string&  key,
  152.                            int            version,
  153.                            const string&  subkey) = 0;
  154.     /// Fetch the BLOB
  155.     ///
  156.     /// @param key 
  157.     ///    BLOB identification key
  158.     /// @param subkey
  159.     ///    BLOB identification subkey
  160.     /// @param version 
  161.     ///    BLOB version
  162.     /// @param 
  163.     ///    buf pointer on destination buffer
  164.     /// @param 
  165.     ///    size buffer size in bytes (chars)
  166.     /// @return 
  167.     ///    FALSE if BLOB doesn't exist or expired
  168.     ///
  169.     /// @note Throws an exception if provided memory buffer is insufficient 
  170.     /// to read the BLOB
  171.     virtual bool Read(const string& key, 
  172.                       int           version, 
  173.                       const string& subkey,
  174.                       void*         buf, 
  175.                       size_t        buf_size) = 0;
  176.     /// Return sequential stream interface to read BLOB data.
  177.     /// 
  178.     /// @param key 
  179.     ///    BLOB identification key
  180.     /// @param subkey
  181.     ///    BLOB identification subkey
  182.     /// @param version 
  183.     ///    BLOB version
  184.     /// @return Interface pointer or NULL if BLOB does not exist
  185.     virtual IReader* GetReadStream(const string&  key, 
  186.                                    int            version,
  187.                                    const string&  subkey) = 0;
  188.     /// Return sequential stream interface to write BLOB data.
  189.     ///
  190.     /// @param key 
  191.     ///    BLOB identification key
  192.     /// @param subkey
  193.     ///    BLOB identification subkey
  194.     /// @param version 
  195.     ///    BLOB version
  196.     /// @return Interface pointer or NULL if BLOB does not exist
  197.     virtual IWriter* GetWriteStream(const string&    key,
  198.                                     int              version,
  199.                                     const string&    subkey) = 0;
  200.     /// Remove all versions of the specified BLOB
  201.     ///
  202.     /// @param key BLOB identification key
  203.     virtual void Remove(const string& key) = 0;
  204.     /// Return last access time for the specified cache entry
  205.     ///
  206.     /// Class implementation may want to implement access time based
  207.     /// aging scheme for cache managed objects. In this case it needs to
  208.     /// track time of every request to BLOB data.
  209.     ///
  210.     /// @param key 
  211.     ///    BLOB identification key
  212.     /// @param subkey
  213.     ///    BLOB identification subkey
  214.     /// @param version 
  215.     ///    BLOB version
  216.     /// @return 
  217.     ///    last access time
  218.     /// @sa TimeStampUpdatePolicy
  219.     virtual time_t GetAccessTime(const string&  key,
  220.                                  int            version,
  221.                                  const string&  subkey) = 0;
  222.     /// Delete all BLOBs older than specified
  223.     ///
  224.     /// @param access_timeout
  225.     ///    Time in seconds. All objects older than this are deleted.
  226.     /// @param keep_last_version 
  227.     ///    type of cleaning action
  228.     virtual void Purge(time_t           access_timeout,
  229.                        EKeepVersions    keep_last_version = eDropAll) = 0;
  230.     /// Delete BLOBs with access time older than specified
  231.     /// 
  232.     /// Function finds all BLOB versions with the specified key
  233.     /// and removes the old instances.
  234.     /// @param key
  235.     ///    BLOB key
  236.     /// @param subkey
  237.     ///    BLOB identification subkey
  238.     /// @param access_timeout 
  239.     ///    Time in seconds. All objects older than this are deleted.
  240.     /// @param keep_last_version 
  241.     ///    type of cleaning action
  242.     virtual void Purge(const string&    key,
  243.                        const string&    subkey,
  244.                        time_t           access_timeout,
  245.                        EKeepVersions    keep_last_version = eDropAll) = 0;
  246.     virtual ~ICache() {}
  247. };
  248. NCBI_DECLARE_INTERFACE_VERSION(ICache,  "icache", 1, 1, 0);
  249. END_NCBI_SCOPE
  250. /*
  251.  * ===========================================================================
  252.  * $Log: icache.hpp,v $
  253.  * Revision 1000.3  2004/06/01 19:39:14  gouriano
  254.  * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.4
  255.  *
  256.  * Revision 1.4  2004/04/19 18:05:40  kuznets
  257.  * Clarification in the comments department
  258.  *
  259.  * Revision 1.3  2003/12/08 16:11:43  kuznets
  260.  * Added plugin mananger support
  261.  *
  262.  * Revision 1.2  2003/11/25 17:12:54  kuznets
  263.  * Reworked cache maintanance methods.
  264.  * Unified cache items expiration functions.
  265.  *
  266.  * Revision 1.1  2003/11/21 12:51:31  kuznets
  267.  * Added new refactored interface for local caching.
  268.  * It's supposed after some work to replace the existing BLOB cache and Int
  269.  * cache and work for all our caching needs.
  270.  * Interface is in the design stage now, all comments are welcome.
  271.  *
  272.  * ===========================================================================
  273.  */
  274. #endif  /* UTIL___BLOB_CACHE__HPP */