ACE/ace/Filecache.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Filecache.h
   6  *
   7  *  @author James Hu
   8  */
   9 //=============================================================================
  10
  11
  12 #ifndef ACE_FILECACHE_H
  13 #define ACE_FILECACHE_H
  14
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/Mem_Map.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/Hash_Map_Manager_T.h"
  24 #include "ace/Null_Mutex.h"
  25 #include "ace/Synch_Traits.h"
  26 #include "ace/RW_Thread_Mutex.h"
  27 #include "ace/OS_NS_sys_stat.h"
  28
  29 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  30
  31 enum ACE_Filecache_Flag
  32 {
  33   ACE_NOMAP = 0,
  34   ACE_MAPIT = 1
  35 };
  36
  37 class ACE_Filecache_Object;
  38
  39 /**
  40  * @class ACE_Filecache_Handle
  41  *
  42  * @brief
  43  * Abstraction over a real file.  This is meant to be the entry
  44  * point into the Cached Virtual Filesystem.
  45  *
  46  * This is a cached filesystem implementation based loosely on the
  47  * implementation of JAWS_File.  The interfaces will be nearly the
  48  * same.  The under-the-hood implementation should hopefully be a
  49  * much faster thing.
  50  * These will be given their own implementations later. For now, we
  51  * borrow the implementation provided by JAWS.
  52  * On creation, the cache is checked, and reference count is
  53  * incremented.  On destruction, reference count is decremented.  If
  54  * the reference count is 0, the file is removed from the cache.
  55  * E.g. 1,
  56  * {
  57  * ACE_Filecache_Handle foo("foo.html");
  58  * this->peer ().send (foo.address (), foo.size ());
  59  * }
  60  * E.g. 2,
  61  * {
  62  * ACE_Filecache_Handle foo("foo.html");
  63  * io->transmitfile (foo.handle (), this->peer ().handle ());
  64  * }
  65  * E.g. 3,
  66  * {
  67  * ACE_Filecache_Handle foo("foo.html", content_length);
  68  * this->peer ().recv (foo.address (), content_length);
  69  * }
  70  * TODO:
  71  */
  72 class ACE_Export ACE_Filecache_Handle
  73 {
  74   // (1) Get rid of the useless copying of files when reading.
  75   // Although it does make sure the file you send isn't being changed,
  76   // it doesn't make sure the file is in a sensible state before
  77   // sending it.
  78   //
  79   // Alternative: if the file get's trashed while it is being shipped,
  80   // let the client request the file again.  The cache should have an
  81   // updated copy by that point.
  82   //
  83   // (2) Use hashing for locating files.  This means I need a hastable
  84   // implementation with buckets.
  85   //
  86   // (3) Only lock when absolutely necessary.  JAWS_Virtual_Filesystem was
  87   // rather conservative, but for some reason it still ran into problems.
  88   // Since this design should be simpler, problems should be easier to spot.
  89   //
  90 public:
  91   /// Query cache for file, and acquire it.  Assumes the file is being
  92   /// opened for reading.
  93   ACE_Filecache_Handle (const ACE_TCHAR *filename,
  94                         ACE_Filecache_Flag mapit = ACE_MAPIT);
  95
  96   /**
  97    * Create new entry, and acquire it.  Presence of SIZE assumes the
  98    * file is being opened for writing.  If SIZE is zero, assumes the
  99    * file is to be removed from the cache.
 100    */
 101   ACE_Filecache_Handle (const ACE_TCHAR *filename,
 102                         int size,
 103                         ACE_Filecache_Flag mapit = ACE_MAPIT);
 104
 105   /// Closes any open handles, release acquired file.
 106   ~ACE_Filecache_Handle ();
 107
 108   /// Base address of memory mapped file.
 109   void *address () const;
 110
 111   /// A handle (e.g., UNIX file descriptor, or NT file handle).
 112   ACE_HANDLE handle () const;
 113
 114   /// Any associated error in handle creation and acquisition.
 115   int error () const;
 116
 117   /// The size of the file.
 118   ACE_OFF_T size () const;
 119
 120 protected:
 121   /// Default do nothing constructor.  Prevent it from being called.
 122   ACE_Filecache_Handle ();
 123
 124   /// Common initializations for constructors.
 125   void init ();
 126
 127 public:
 128   /// These come from ACE_Filecache_Object, which is an internal class.
 129   enum
 130   {
 131     ACE_SUCCESS = 0,
 132     ACE_ACCESS_FAILED,
 133     ACE_OPEN_FAILED,
 134     ACE_COPY_FAILED,
 135     ACE_STAT_FAILED,
 136     ACE_MEMMAP_FAILED,
 137     ACE_WRITE_FAILED
 138   };
 139
 140 private:
 141   /// A reference to the low level instance.
 142   ACE_Filecache_Object *file_;
 143
 144   /// A dup'd version of the one from file_.
 145   ACE_HANDLE handle_;
 146 };
 147
 148 typedef ACE_Hash_Map_Manager_Ex<const ACE_TCHAR *, ACE_Filecache_Object *, ACE_Hash<const ACE_TCHAR *>, ACE_Equal_To<const ACE_TCHAR *>, ACE_Null_Mutex>
 149         ACE_Filecache_Hash;
 150
 151 typedef ACE_Hash_Map_Entry<const ACE_TCHAR *, ACE_Filecache_Object *> ACE_Filecache_Hash_Entry;
 152
 153 /**
 154  * @class ACE_Filecache
 155  *
 156  * @brief
 157  * A hash table holding the information about entry point into
 158  * the Cached Virtual Filesystem. On insertion, the reference
 159  * count is incremented. On destruction, reference count is
 160  * decremented.
 161  */
 162 class ACE_Export ACE_Filecache
 163 {
 164 public:
 165   /// Singleton pattern.
 166   static ACE_Filecache *instance ();
 167
 168   ~ACE_Filecache ();
 169
 170   /// Returns 0 if the file associated with ``filename'' is in the cache,
 171   /// or -1 if not.
 172   int find (const ACE_TCHAR *filename);
 173
 174   /// Return the file associated with ``filename'' if it is in the cache,
 175   /// or create if not.
 176   ACE_Filecache_Object *fetch (const ACE_TCHAR *filename, int mapit = 1);
 177
 178   /// Remove the file associated with ``filename'' from the cache.
 179   ACE_Filecache_Object *remove (const ACE_TCHAR *filename);
 180
 181   /// Create a new Filecache_Object, returns it.
 182   ACE_Filecache_Object *create (const ACE_TCHAR *filename, int size);
 183
 184   /// Release an acquired Filecache_Object, returns it again or NULL if it
 185   /// was deleted.
 186   ACE_Filecache_Object *finish (ACE_Filecache_Object *&new_file);
 187
 188   ACE_ALLOC_HOOK_DECLARE;
 189
 190 protected:
 191   ACE_Filecache_Object *insert_i (const ACE_TCHAR *filename,
 192                                   ACE_SYNCH_RW_MUTEX &filelock,
 193                                   int mapit);
 194   ACE_Filecache_Object *remove_i (const ACE_TCHAR *filename);
 195   ACE_Filecache_Object *update_i (const ACE_TCHAR *filename,
 196                                   ACE_SYNCH_RW_MUTEX &filelock,
 197                                   int mapit);
 198
 199 public:
 200   enum
 201   {
 202     /// For this stupid implementation, use an array.  Someday, use a
 203     /// balanced search tree, or real hash table.
 204     ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE = 512,
 205
 206     /// This determines the highwater mark in megabytes for the cache.
 207     /// This will be ignored for now.
 208     ACE_DEFAULT_VIRTUAL_FILESYSTEM_CACHE_SIZE = 20
 209   };
 210
 211 protected:
 212   /// Prevent it from being called.
 213   ACE_Filecache ();
 214
 215 private:
 216   ACE_OFF_T size_;
 217
 218   /// The hash table
 219   ACE_Filecache_Hash hash_;
 220
 221   /// The reference to the instance
 222   static ACE_Filecache *cvf_;
 223
 224   // = Synchronization variables.
 225   ACE_SYNCH_RW_MUTEX hash_lock_[ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE];
 226   ACE_SYNCH_RW_MUTEX file_lock_[ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE];
 227 };
 228
 229 /**
 230  * @class ACE_Filecache_Object
 231  *
 232  * @brief
 233  * Abstraction over a real file.  This is what the Virtual
 234  * Filesystem contains.  This class is not intended for general
 235  * consumption.  Please consult a physician before attempting to
 236  * use this class.
 237  */
 238 class ACE_Export ACE_Filecache_Object
 239 {
 240 public:
 241   friend class ACE_Filecache;
 242
 243   /// Creates a file for reading.
 244   ACE_Filecache_Object (const ACE_TCHAR *filename,
 245                         ACE_SYNCH_RW_MUTEX &lock,
 246                         LPSECURITY_ATTRIBUTES sa = 0,
 247                         int mapit = 1);
 248
 249   /// Creates a file for writing.
 250   ACE_Filecache_Object (const ACE_TCHAR *filename,
 251                         ACE_OFF_T size,
 252                         ACE_SYNCH_RW_MUTEX &lock,
 253                         LPSECURITY_ATTRIBUTES sa = 0);
 254
 255   /// Only if reference count is zero should this be called.
 256   ~ACE_Filecache_Object ();
 257
 258   /// Increment the reference_count_.
 259   int acquire ();
 260
 261   /// Decrement the reference_count_.
 262   int release ();
 263
 264   // = error_ accessors
 265   int error () const;
 266   int error (int error_value,
 267              const ACE_TCHAR *s = ACE_TEXT ("ACE_Filecache_Object"));
 268
 269   /// filename_ accessor
 270   const ACE_TCHAR *filename () const;
 271
 272   /// handle_ accessor.
 273   ACE_HANDLE handle () const;
 274
 275   /// Base memory address for memory mapped file.
 276   void *address () const;
 277
 278   /// size_ accessor.
 279   ACE_OFF_T size () const;
 280
 281   /// True if file on disk is newer than cached file.
 282   int update () const;
 283
 284   ACE_ALLOC_HOOK_DECLARE;
 285
 286 protected:
 287   /// Prevent from being called.
 288   ACE_Filecache_Object ();
 289
 290   /// Common initialization code,
 291   void init ();
 292
 293 private:
 294   /// Internal error logging method, no locking.
 295   int error_i (int error_value,
 296                const ACE_TCHAR *s = ACE_TEXT ("ACE_Filecache_Object"));
 297
 298 public:
 299   enum Creation_States
 300   {
 301     ACE_READING = 1,
 302     ACE_WRITING = 2
 303   };
 304
 305   enum Error_Conditions
 306   {
 307     ACE_SUCCESS = 0,
 308     ACE_ACCESS_FAILED,
 309     ACE_OPEN_FAILED,
 310     ACE_COPY_FAILED,
 311     ACE_STAT_FAILED,
 312     ACE_MEMMAP_FAILED,
 313     ACE_WRITE_FAILED
 314   };
 315
 316 private:
 317   /// The temporary file name and the real file name.  The real file is
 318   /// copied into the temporary file for safety reasons.
 319   ACE_TCHAR *tempname_;
 320   ACE_TCHAR filename_[MAXPATHLEN + 1];
 321
 322   /// Holds the memory mapped version of the temporary file.
 323   ACE_Mem_Map mmap_;
 324
 325   /// The descriptor to the temporary file.
 326   ACE_HANDLE handle_;
 327
 328   /// Used to compare against the real file to test if an update is needed.
 329   ACE_stat stat_;
 330   ACE_OFF_T size_;
 331
 332   /// Status indicators.
 333   int action_;
 334   int error_;
 335
 336   /// If set to 1, means the object is flagged for removal.
 337   int stale_;
 338
 339   /// Security attribute object.
 340   LPSECURITY_ATTRIBUTES sa_;
 341
 342   /// The default initializer
 343   ACE_SYNCH_RW_MUTEX junklock_;
 344
 345   /// Provides a bookkeeping mechanism for users of this object.
 346   ACE_SYNCH_RW_MUTEX &lock_;
 347 };
 348
 349 ACE_END_VERSIONED_NAMESPACE_DECL
 350
 351 #include /**/ "ace/post.h"
 352
 353 #endif /* ACE_FILECACHE_H */