dep/ACE_wrappers/ace/Filecache.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Filecache.h
   6  *
   7  *  $Id: Filecache.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author James Hu
  10  */
  11 //=============================================================================
  12
  13
  14 #ifndef ACE_FILECACHE_H
  15 #define ACE_FILECACHE_H
  16
  17 #include /**/ "ace/pre.h"
  18
  19 #include "ace/Mem_Map.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #include "ace/Hash_Map_Manager_T.h"
  26 #include "ace/Null_Mutex.h"
  27 #include "ace/Synch_Traits.h"
  28 #include "ace/RW_Thread_Mutex.h"
  29 #include "ace/OS_NS_sys_stat.h"
  30
  31 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  32
  33 enum ACE_Filecache_Flag
  34 {
  35   ACE_NOMAP = 0,
  36   ACE_MAPIT = 1
  37 };
  38
  39 class ACE_Filecache_Object;
  40
  41 /**
  42  * @class ACE_Filecache_Handle
  43  *
  44  * @brief Abstraction over a real file.  This is meant to be the entry
  45  * point into the Cached Virtual Filesystem.
  46  *
  47  * This is a cached filesystem implementation based loosely on the
  48  * implementation of JAWS_File.  The interfaces will be nearly the
  49  * same.  The under-the-hood implementation should hopefully be a
  50  * much faster thing.
  51  * These will be given their own implementations later. For now, we
  52  * borrow the implementation provided by JAWS.
  53  * On creation, the cache is checked, and reference count is
  54  * incremented.  On destruction, reference count is decremented.  If
  55  * the reference count is 0, the file is removed from the cache.
  56  * E.g. 1,
  57  * {
  58  * ACE_Filecache_Handle foo("foo.html");
  59  * this->peer ().send (foo.address (), foo.size ());
  60  * }
  61  * E.g. 2,
  62  * {
  63  * ACE_Filecache_Handle foo("foo.html");
  64  * io->transmitfile (foo.handle (), this->peer ().handle ());
  65  * }
  66  * E.g. 3,
  67  * {
  68  * ACE_Filecache_Handle foo("foo.html", content_length);
  69  * this->peer ().recv (foo.address (), content_length);
  70  * }
  71  * TODO:
  72  */
  73 class ACE_Export ACE_Filecache_Handle
  74 {
  75   // (1) Get rid of the useless copying of files when reading.
  76   // Although it does make sure the file you send isn't being changed,
  77   // it doesn't make sure the file is in a sensible state before
  78   // sending it.
  79   //
  80   // Alternative: if the file get's trashed while it is being shipped,
  81   // let the client request the file again.  The cache should have an
  82   // updated copy by that point.
  83   //
  84   // (2) Use hashing for locating files.  This means I need a hastable
  85   // implementation with buckets.
  86   //
  87   // (3) Only lock when absolutely necessary.  JAWS_Virtual_Filesystem was
  88   // rather conservative, but for some reason it still ran into problems.
  89   // Since this design should be simpler, problems should be easier to spot.
  90   //
  91 public:
  92
  93   /// Query cache for file, and acquire it.  Assumes the file is being
  94   /// opened for reading.
  95   ACE_Filecache_Handle (const ACE_TCHAR *filename,
  96                         ACE_Filecache_Flag mapit = ACE_MAPIT);
  97
  98   /**
  99    * Create new entry, and acquire it.  Presence of SIZE assumes the
 100    * file is being opened for writing.  If SIZE is zero, assumes the
 101    * file is to be removed from the cache.
 102    */
 103   ACE_Filecache_Handle (const ACE_TCHAR *filename,
 104                         int size,
 105                         ACE_Filecache_Flag mapit = ACE_MAPIT);
 106
 107   /// Closes any open handles, release acquired file.
 108   ~ACE_Filecache_Handle (void);
 109
 110   /// Base address of memory mapped file.
 111   void *address (void) const;
 112
 113   /// A handle (e.g., UNIX file descriptor, or NT file handle).
 114   ACE_HANDLE handle (void) const;
 115
 116   /// Any associated error in handle creation and acquisition.
 117   int error (void) const;
 118
 119   /// The size of the file.
 120   ACE_OFF_T size (void) const;
 121
 122 protected:
 123   /// Default do nothing constructor.  Prevent it from being called.
 124   ACE_Filecache_Handle (void);
 125
 126   /// Common initializations for constructors.
 127   void init (void);
 128
 129 public:
 130   /// These come from ACE_Filecache_Object, which is an internal class.
 131   enum
 132   {
 133     ACE_SUCCESS = 0,
 134     ACE_ACCESS_FAILED,
 135     ACE_OPEN_FAILED,
 136     ACE_COPY_FAILED,
 137     ACE_STAT_FAILED,
 138     ACE_MEMMAP_FAILED,
 139     ACE_WRITE_FAILED
 140   };
 141
 142 private:
 143   /// A reference to the low level instance.
 144   ACE_Filecache_Object *file_;
 145
 146   /// A <dup>'d version of the one from <file_>.
 147   ACE_HANDLE handle_;
 148
 149   int mapit_;
 150 };
 151
 152 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>
 153         ACE_Filecache_Hash;
 154
 155 typedef ACE_Hash_Map_Entry<const ACE_TCHAR *, ACE_Filecache_Object *> ACE_Filecache_Hash_Entry;
 156
 157 /**
 158  * @class ACE_Filecache
 159  *
 160  * @brief A hash table holding the information about entry point into
 161  * the Cached Virtual Filesystem. On insertion, the reference
 162  * count is incremented. On destruction, reference count is
 163  * decremented.
 164  */
 165 class ACE_Export ACE_Filecache
 166 {
 167 public:
 168   /// Singleton pattern.
 169   static ACE_Filecache *instance (void);
 170
 171   ~ACE_Filecache (void);
 172
 173   /// Returns 0 if the file associated with ``filename'' is in the cache,
 174   /// or -1 if not.
 175   int find (const ACE_TCHAR *filename);
 176
 177   /// Return the file associated with ``filename'' if it is in the cache,
 178   /// or create if not.
 179   ACE_Filecache_Object *fetch (const ACE_TCHAR *filename, int mapit = 1);
 180
 181   /// Remove the file associated with ``filename'' from the cache.
 182   ACE_Filecache_Object *remove (const ACE_TCHAR *filename);
 183
 184   /// Create a new Filecache_Object, returns it.
 185   ACE_Filecache_Object *create (const ACE_TCHAR *filename, int size);
 186
 187   /// Release an acquired Filecache_Object, returns it again or NULL if it
 188   /// was deleted.
 189   ACE_Filecache_Object *finish (ACE_Filecache_Object *&new_file);
 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 Abstraction over a real file.  This is what the Virtual
 235  * Filesystem contains.  This class is not intended for general
 236  * consumption.  Please consult a physician before attempting to
 237  * use this class.
 238  */
 239 class ACE_Export ACE_Filecache_Object
 240 {
 241 public:
 242   friend class ACE_Filecache;
 243
 244   /// Creates a file for reading.
 245   ACE_Filecache_Object (const ACE_TCHAR *filename,
 246                         ACE_SYNCH_RW_MUTEX &lock,
 247                         LPSECURITY_ATTRIBUTES sa = 0,
 248                         int mapit = 1);
 249
 250   /// Creates a file for writing.
 251   ACE_Filecache_Object (const ACE_TCHAR *filename,
 252                         ACE_OFF_T size,
 253                         ACE_SYNCH_RW_MUTEX &lock,
 254                         LPSECURITY_ATTRIBUTES sa = 0);
 255
 256   /// Only if reference count is zero should this be called.
 257   ~ACE_Filecache_Object (void);
 258
 259   /// Increment the reference_count_.
 260   int acquire (void);
 261
 262   /// Decrement the reference_count_.
 263   int release (void);
 264
 265   // = error_ accessors
 266   int error (void) const;
 267   int error (int error_value,
 268              const ACE_TCHAR *s = ACE_TEXT ("ACE_Filecache_Object"));
 269
 270   /// filename_ accessor
 271   const ACE_TCHAR *filename (void) const;
 272
 273   /// handle_ accessor.
 274   ACE_HANDLE handle (void) const;
 275
 276   /// Base memory address for memory mapped file.
 277   void *address (void) const;
 278
 279   /// size_ accessor.
 280   ACE_OFF_T size (void) const;
 281
 282   /// True if file on disk is newer than cached file.
 283   int update (void) const;
 284
 285 protected:
 286   /// Prevent from being called.
 287   ACE_Filecache_Object (void);
 288
 289   /// Common initialization code,
 290   void init (void);
 291
 292 private:
 293   /// Internal error logging method, no locking.
 294   int error_i (int error_value,
 295                const ACE_TCHAR *s = ACE_TEXT ("ACE_Filecache_Object"));
 296
 297 public:
 298
 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 */