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
  92   /// Query cache for file, and acquire it.  Assumes the file is being
  93   /// opened for reading.
  94   ACE_Filecache_Handle (const ACE_TCHAR *filename,
  95                         ACE_Filecache_Flag mapit = ACE_MAPIT);
  96
  97   /**
  98    * Create new entry, and acquire it.  Presence of SIZE assumes the
  99    * file is being opened for writing.  If SIZE is zero, assumes the
 100    * file is to be removed from the cache.
 101    */
 102   ACE_Filecache_Handle (const ACE_TCHAR *filename,
 103                         int size,
 104                         ACE_Filecache_Flag mapit = ACE_MAPIT);
 105
 106   /// Closes any open handles, release acquired file.
 107   ~ACE_Filecache_Handle (void);
 108
 109   /// Base address of memory mapped file.
 110   void *address (void) const;
 111
 112   /// A handle (e.g., UNIX file descriptor, or NT file handle).
 113   ACE_HANDLE handle (void) const;
 114
 115   /// Any associated error in handle creation and acquisition.
 116   int error (void) const;
 117
 118   /// The size of the file.
 119   ACE_OFF_T size (void) const;
 120
 121 protected:
 122   /// Default do nothing constructor.  Prevent it from being called.
 123   ACE_Filecache_Handle (void);
 124
 125   /// Common initializations for constructors.
 126   void init (void);
 127
 128 public:
 129   /// These come from ACE_Filecache_Object, which is an internal class.
 130   enum
 131   {
 132     ACE_SUCCESS = 0,
 133     ACE_ACCESS_FAILED,
 134     ACE_OPEN_FAILED,
 135     ACE_COPY_FAILED,
 136     ACE_STAT_FAILED,
 137     ACE_MEMMAP_FAILED,
 138     ACE_WRITE_FAILED
 139   };
 140
 141 private:
 142   /// A reference to the low level instance.
 143   ACE_Filecache_Object *file_;
 144
 145   /// A dup'd version of the one from file_.
 146   ACE_HANDLE handle_;
 147 };
 148
 149 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>
 150         ACE_Filecache_Hash;
 151
 152 typedef ACE_Hash_Map_Entry<const ACE_TCHAR *, ACE_Filecache_Object *> ACE_Filecache_Hash_Entry;
 153
 154 /**
 155  * @class ACE_Filecache
 156  *
 157  * @brief
 158  * A hash table holding the information about entry point into
 159  * the Cached Virtual Filesystem. On insertion, the reference
 160  * count is incremented. On destruction, reference count is
 161  * decremented.
 162  */
 163 class ACE_Export ACE_Filecache
 164 {
 165 public:
 166   /// Singleton pattern.
 167   static ACE_Filecache *instance (void);
 168
 169   ~ACE_Filecache (void);
 170
 171   /// Returns 0 if the file associated with ``filename'' is in the cache,
 172   /// or -1 if not.
 173   int find (const ACE_TCHAR *filename);
 174
 175   /// Return the file associated with ``filename'' if it is in the cache,
 176   /// or create if not.
 177   ACE_Filecache_Object *fetch (const ACE_TCHAR *filename, int mapit = 1);
 178
 179   /// Remove the file associated with ``filename'' from the cache.
 180   ACE_Filecache_Object *remove (const ACE_TCHAR *filename);
 181
 182   /// Create a new Filecache_Object, returns it.
 183   ACE_Filecache_Object *create (const ACE_TCHAR *filename, int size);
 184
 185   /// Release an acquired Filecache_Object, returns it again or NULL if it
 186   /// was deleted.
 187   ACE_Filecache_Object *finish (ACE_Filecache_Object *&new_file);
 188
 189   ACE_ALLOC_HOOK_DECLARE;
 190
 191 protected:
 192   ACE_Filecache_Object *insert_i (const ACE_TCHAR *filename,
 193                                   ACE_SYNCH_RW_MUTEX &filelock,
 194                                   int mapit);
 195   ACE_Filecache_Object *remove_i (const ACE_TCHAR *filename);
 196   ACE_Filecache_Object *update_i (const ACE_TCHAR *filename,
 197                                   ACE_SYNCH_RW_MUTEX &filelock,
 198                                   int mapit);
 199
 200 public:
 201
 202   enum
 203   {
 204     /// For this stupid implementation, use an array.  Someday, use a
 205     /// balanced search tree, or real hash table.
 206     ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE = 512,
 207
 208     /// This determines the highwater mark in megabytes for the cache.
 209     /// This will be ignored for now.
 210     ACE_DEFAULT_VIRTUAL_FILESYSTEM_CACHE_SIZE = 20
 211   };
 212
 213 protected:
 214   /// Prevent it from being called.
 215   ACE_Filecache (void);
 216
 217 private:
 218   ACE_OFF_T size_;
 219
 220   /// The hash table
 221   ACE_Filecache_Hash hash_;
 222
 223   /// The reference to the instance
 224   static ACE_Filecache *cvf_;
 225
 226   // = Synchronization variables.
 227   ACE_SYNCH_RW_MUTEX hash_lock_[ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE];
 228   ACE_SYNCH_RW_MUTEX file_lock_[ACE_DEFAULT_VIRTUAL_FILESYSTEM_TABLE_SIZE];
 229 };
 230
 231 /**
 232  * @class ACE_Filecache_Object
 233  *
 234  * @brief
 235  * Abstraction over a real file.  This is what the Virtual
 236  * Filesystem contains.  This class is not intended for general
 237  * consumption.  Please consult a physician before attempting to
 238  * use this class.
 239  */
 240 class ACE_Export ACE_Filecache_Object
 241 {
 242 public:
 243   friend class ACE_Filecache;
 244
 245   /// Creates a file for reading.
 246   ACE_Filecache_Object (const ACE_TCHAR *filename,
 247                         ACE_SYNCH_RW_MUTEX &lock,
 248                         LPSECURITY_ATTRIBUTES sa = 0,
 249                         int mapit = 1);
 250
 251   /// Creates a file for writing.
 252   ACE_Filecache_Object (const ACE_TCHAR *filename,
 253                         ACE_OFF_T size,
 254                         ACE_SYNCH_RW_MUTEX &lock,
 255                         LPSECURITY_ATTRIBUTES sa = 0);
 256
 257   /// Only if reference count is zero should this be called.
 258   ~ACE_Filecache_Object (void);
 259
 260   /// Increment the reference_count_.
 261   int acquire (void);
 262
 263   /// Decrement the reference_count_.
 264   int release (void);
 265
 266   // = error_ accessors
 267   int error (void) const;
 268   int error (int error_value,
 269              const ACE_TCHAR *s = ACE_TEXT ("ACE_Filecache_Object"));
 270
 271   /// filename_ accessor
 272   const ACE_TCHAR *filename (void) const;
 273
 274   /// handle_ accessor.
 275   ACE_HANDLE handle (void) const;
 276
 277   /// Base memory address for memory mapped file.
 278   void *address (void) const;
 279
 280   /// size_ accessor.
 281   ACE_OFF_T size (void) const;
 282
 283   /// True if file on disk is newer than cached file.
 284   int update (void) const;
 285
 286   ACE_ALLOC_HOOK_DECLARE;
 287
 288 protected:
 289   /// Prevent from being called.
 290   ACE_Filecache_Object (void);
 291
 292   /// Common initialization code,
 293   void init (void);
 294
 295 private:
 296   /// Internal error logging method, no locking.
 297   int error_i (int error_value,
 298                const ACE_TCHAR *s = ACE_TEXT ("ACE_Filecache_Object"));
 299
 300 public:
 301   enum Creation_States
 302   {
 303     ACE_READING = 1,
 304     ACE_WRITING = 2
 305   };
 306
 307   enum Error_Conditions
 308   {
 309     ACE_SUCCESS = 0,
 310     ACE_ACCESS_FAILED,
 311     ACE_OPEN_FAILED,
 312     ACE_COPY_FAILED,
 313     ACE_STAT_FAILED,
 314     ACE_MEMMAP_FAILED,
 315     ACE_WRITE_FAILED
 316   };
 317
 318 private:
 319   /// The temporary file name and the real file name.  The real file is
 320   /// copied into the temporary file for safety reasons.
 321   ACE_TCHAR *tempname_;
 322   ACE_TCHAR filename_[MAXPATHLEN + 1];
 323
 324   /// Holds the memory mapped version of the temporary file.
 325   ACE_Mem_Map mmap_;
 326
 327   /// The descriptor to the temporary file.
 328   ACE_HANDLE handle_;
 329
 330   /// Used to compare against the real file to test if an update is needed.
 331   ACE_stat stat_;
 332   ACE_OFF_T size_;
 333
 334   /// Status indicators.
 335   int action_;
 336   int error_;
 337
 338   /// If set to 1, means the object is flagged for removal.
 339   int stale_;
 340
 341   /// Security attribute object.
 342   LPSECURITY_ATTRIBUTES sa_;
 343
 344   /// The default initializer
 345   ACE_SYNCH_RW_MUTEX junklock_;
 346
 347   /// Provides a bookkeeping mechanism for users of this object.
 348   ACE_SYNCH_RW_MUTEX &lock_;
 349 };
 350
 351 ACE_END_VERSIONED_NAMESPACE_DECL
 352
 353 #include /**/ "ace/post.h"
 354
 355 #endif /* ACE_FILECACHE_H */