dep/ACE_wrappers/ace/MMAP_Memory_Pool.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file     MMAP_Memory_Pool.h
   6  *
   7  *  $Id: MMAP_Memory_Pool.h 81589 2008-05-02 13:07:33Z johnnyw $
   8  *
   9  *  @author Dougls C. Schmidt <schmidt@cs.wustl.edu>
  10  *  @author Prashant Jain <pjain@cs.wustl.edu>
  11  */
  12 //=============================================================================
  13
  14 #ifndef ACE_MMAP_MEMORY_POOL_H
  15 #define ACE_MMAP_MEMORY_POOL_H
  16
  17 #include /**/ "ace/pre.h"
  18
  19 #include /**/ "ace/ACE_export.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #include "ace/ACE.h"
  26 #include "ace/Event_Handler.h"
  27 #include "ace/Sig_Handler.h"
  28 #include "ace/Mem_Map.h"
  29
  30 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  31
  32 /**
  33  * @class ACE_MMAP_Memory_Pool_Options
  34  *
  35  * @brief Helper class for MMAP Memory Pool constructor options.
  36  *
  37  * This should be a nested class, but that breaks too many
  38  * compilers.
  39  */
  40 class ACE_Export ACE_MMAP_Memory_Pool_Options
  41 {
  42 public:
  43   enum
  44   {
  45     /**
  46      * The base address from the first call to mmap will be used for subsequent
  47      * calls to mmap.
  48      */
  49     FIRSTCALL_FIXED = 0,
  50
  51     /**
  52      * The base address specified in base_addr will be used in all calls to
  53      * mmap.
  54      */
  55     ALWAYS_FIXED = 1,
  56
  57     /**
  58      * The base address will be selected by the OS for each call to mmap.
  59      * Caution should be used with this mode since a call that requires the
  60      * backing store to grow may change pointers that are cached by the
  61      * application.
  62      */
  63     NEVER_FIXED = 2
  64   };
  65
  66   /// Constructor
  67   ACE_MMAP_Memory_Pool_Options (const void *base_addr = ACE_DEFAULT_BASE_ADDR,
  68                                 int use_fixed_addr = ALWAYS_FIXED,
  69                                 bool write_each_page = true,
  70                                 size_t minimum_bytes = 0,
  71                                 u_int flags = 0,
  72                                 bool guess_on_fault = true,
  73                                 LPSECURITY_ATTRIBUTES sa = 0,
  74                                 mode_t file_mode = ACE_DEFAULT_FILE_PERMS,
  75                                 bool unique_ = false,
  76                                 bool install_signal_handler = true);
  77
  78   /// Base address of the memory-mapped backing store.
  79   const void *base_addr_;
  80
  81   /**
  82    * Determines whether we set @c base_addr_ or if mmap(2) selects it
  83    * FIRSTCALL_FIXED The base address from the first call to mmap
  84    *                 will be used for subsequent calls to mmap
  85    * ALWAYS_FIXED    The base address specified in base_addr will be
  86    *                 used in all calls to mmap.
  87    * NEVER_FIXED     The base address will be selected by the OS for
  88    *                 each call to mmap. Caution should be used with
  89    *                 this mode since a call that requires the backing
  90    *                 store to grow may change pointers that are
  91    *                 cached by the application.
  92    */
  93   int use_fixed_addr_;
  94
  95   /// Should each page be written eagerly to avoid surprises later
  96   /// on?
  97   bool write_each_page_;
  98
  99   /// What the minimim bytes of the initial segment should be.
 100   size_t minimum_bytes_;
 101
 102   /// Any special flags that need to be used for @c mmap.
 103   u_int flags_;
 104
 105   /**
 106    * Try to remap without knowing the faulting address.  This
 107    * parameter is ignored on platforms that know the faulting address
 108    * (UNIX with SI_ADDR and Win32).
 109    */
 110   bool guess_on_fault_;
 111
 112   /// Pointer to a security attributes object.  Only used on NT.
 113   LPSECURITY_ATTRIBUTES sa_;
 114
 115   /// File mode for mmaped file, if it is created.
 116   mode_t file_mode_;
 117
 118   /// Do we want an unique backing store name?
 119   bool unique_;
 120
 121   /// Should we install a signal handler
 122   bool install_signal_handler_;
 123
 124 private:
 125   // Prevent copying
 126   ACE_MMAP_Memory_Pool_Options (const ACE_MMAP_Memory_Pool_Options &);
 127   ACE_MMAP_Memory_Pool_Options &operator= (const ACE_MMAP_Memory_Pool_Options &);
 128 };
 129
 130 /**
 131  * @class ACE_MMAP_Memory_Pool
 132  *
 133  * @brief Make a memory pool that is based on @c mmap(2).  This
 134  * implementation allows memory to be shared between processes.
 135  */
 136 class ACE_Export ACE_MMAP_Memory_Pool : public ACE_Event_Handler
 137 {
 138 public:
 139   typedef ACE_MMAP_Memory_Pool_Options OPTIONS;
 140
 141   // = Initialization and termination methods.
 142
 143   /// Initialize the pool.
 144   ACE_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0,
 145                         const OPTIONS *options = 0);
 146
 147   /// Destructor.
 148   virtual ~ACE_MMAP_Memory_Pool (void);
 149
 150   /// Ask system for initial chunk of shared memory.
 151   virtual void *init_acquire (size_t nbytes,
 152                               size_t &rounded_bytes,
 153                               int &first_time);
 154
 155   /**
 156    * Acquire at least @a nbytes from the memory pool. @a rounded_bytes
 157    * is the actual number of bytes allocated.  Also acquires an
 158    * internal semaphore that ensures proper serialization of
 159    * ACE_MMAP_Memory_Pool initialization across processes.
 160    */
 161   virtual void *acquire (size_t nbytes,
 162                          size_t &rounded_bytes);
 163
 164   /// Instruct the memory pool to release all of its resources.
 165   virtual int release (int destroy = 1);
 166
 167   /// Sync the memory region to the backing store starting at
 168   /// @c this->base_addr_.
 169   virtual int sync (size_t len, int flags = MS_SYNC);
 170
 171   /// Sync the memory region to the backing store starting at
 172   /// @c this->base_addr_.  Will sync as much as the backing file
 173   /// allows.
 174   virtual int sync (int flags = MS_SYNC);
 175
 176   /// Sync the memory region to the backing store starting at @a addr.
 177   virtual int sync (void *addr, size_t len, int flags = MS_SYNC);
 178
 179   /**
 180    * Change the protection of the pages of the mapped region to @a prot
 181    * starting at @c this->base_addr_ up to @a len bytes.  If @a len == -1
 182    * then change protection of all pages in the mapped region.
 183    */
 184   virtual int protect (size_t len, int prot = PROT_RDWR);
 185
 186   /**
 187    * Change the protection of all the pages of the mapped region to @a prot
 188    * starting at @c this->base_addr_.
 189    */
 190   virtual int protect (int prot = PROT_RDWR);
 191
 192   /// Change the protection of the pages of the mapped region to @a prot
 193   /// starting at @a addr up to @a len bytes.
 194   virtual int protect (void *addr, size_t len, int prot = PROT_RDWR);
 195
 196 #if defined (ACE_WIN32)
 197   /**
 198    * Win32 Structural exception selector.  The return value decides
 199    * how to handle memory pool related structural exceptions.  Returns
 200    * 1, 0, or , -1.
 201    */
 202   virtual int seh_selector (void *);
 203 #endif /* ACE_WIN32 */
 204
 205   /**
 206    * Try to extend the virtual address space so that @a addr is now
 207    * covered by the address mapping.  The method succeeds and returns
 208    * 0 if the backing store has adequate memory to cover this address.
 209    * Otherwise, it returns -1.  This method is typically called by a
 210    * UNIX signal handler for SIGSEGV or a Win32 structured exception
 211    * when another process has grown the backing store (and its
 212    * mapping) and our process now incurs a fault because our mapping
 213    * isn't in range (yet).
 214    */
 215   virtual int remap (void *addr);
 216
 217   /// Return the base address of this memory pool.
 218   virtual void *base_addr (void) const;
 219
 220   /// Dump the state of an object.
 221   virtual void dump (void) const;
 222
 223   /// Get reference to underlying ACE_Mem_Map object.
 224   ACE_Mem_Map const & mmap (void) const;
 225
 226   /// Get reference to underlying ACE_Mem_Map object.
 227   ACE_Mem_Map & mmap (void);
 228
 229   /// Declare the dynamic allocation hooks.
 230   ACE_ALLOC_HOOK_DECLARE;
 231
 232 protected:
 233   /// Implement the algorithm for rounding up the request to an
 234   /// appropriate chunksize.
 235   virtual size_t round_up (size_t nbytes);
 236
 237   /// Compute the new @a map_size of the backing store and commit the
 238   /// memory.
 239   virtual int commit_backing_store_name (size_t rounded_bytes,
 240                                          size_t & map_size);
 241
 242   /// Memory map the file up to @a map_size bytes.
 243   virtual int map_file (size_t map_size);
 244
 245 #if !defined (ACE_WIN32)
 246   /**
 247    * Handle SIGSEGV and SIGBUS signals to remap memory properly.  When a
 248    * process reads or writes to non-mapped memory a signal (SIGBUS or
 249    * SIGSEGV) will be triggered.  At that point, the ACE_Sig_Handler
 250    * (which is part of the ACE_Reactor) will catch the signal and
 251    * dispatch the handle_signal() method defined here.  If the SIGSEGV
 252    * signal occurred due to the fact that the mapping wasn't uptodate
 253    * with respect to the backing store, the handler method below will
 254    * update the mapping accordingly.  When the signal handler returns,
 255    * the instruction should be restarted and the operation should work.
 256    */
 257   virtual int handle_signal (int signum, siginfo_t *, ucontext_t *);
 258 #endif
 259
 260 #if !defined (ACE_WIN32)
 261   /// Handles SIGSEGV.
 262   ACE_Sig_Handler signal_handler_;
 263 #endif
 264
 265   /// Memory-mapping object.
 266   ACE_Mem_Map mmap_;
 267
 268   /**
 269    * Base of mapped region.  If this has the value of 0 then the OS is
 270    * free to select any address to map the file, otherwise this value
 271    * is what the OS must try to use to mmap the file.
 272    */
 273   void *base_addr_;
 274
 275   /// Must we use the @c base_addr_ or can we let mmap(2) select it?
 276   int use_fixed_addr_;
 277
 278   /// Flags passed into ACE_OS::mmap().
 279   int flags_;
 280
 281   /// Should we write a byte to each page to forceably allocate memory
 282   /// for this backing store?
 283   bool write_each_page_;
 284
 285   /// What the minimum bytes of the initial segment should be.
 286   size_t minimum_bytes_;
 287
 288   /// Name of the backing store where the shared memory pool is kept.
 289   ACE_TCHAR backing_store_name_[MAXPATHLEN + 1];
 290
 291   /**
 292    * Try to remap without knowing the faulting address.  This
 293    * parameter is ignored on platforms that know the faulting address
 294    * (UNIX with SI_ADDR and Win32).
 295    */
 296   bool guess_on_fault_;
 297
 298   /// Security attributes object, only used on NT.
 299   LPSECURITY_ATTRIBUTES sa_;
 300
 301   /// Protection mode for mmaped file.
 302   mode_t file_mode_;
 303
 304   /// Should we install a signal handler
 305   bool install_signal_handler_;
 306 };
 307
 308 /**
 309  * @class ACE_Lite_MMAP_Memory_Pool
 310  *
 311  * @brief Make a ``lighter-weight'' memory pool based ACE_Mem_Map.
 312  *
 313  * This implementation allows memory to be shared between
 314  * processes.  However, unlike the ACE_MMAP_Memory_Pool
 315  * the @c sync methods are no-ops, which means that we don't pay
 316  * for the price of flushing the memory to the backing store on
 317  * every update.  Naturally, this trades off increased
 318  * performance for less reliability if the machine crashes.
 319  */
 320 class ACE_Export ACE_Lite_MMAP_Memory_Pool : public ACE_MMAP_Memory_Pool
 321 {
 322 public:
 323   /// Initialize the pool.
 324   ACE_Lite_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0,
 325                              const OPTIONS *options = 0);
 326
 327   /// Destructor.
 328   virtual ~ACE_Lite_MMAP_Memory_Pool (void);
 329
 330   /// Overwrite the default sync behavior with no-op
 331   virtual int sync (size_t len, int flags = MS_SYNC);
 332
 333   /// Overwrite the default sync behavior with no-op
 334   virtual int sync (int flags = MS_SYNC);
 335
 336   /// Overwrite the default sync behavior with no-op
 337   virtual int sync (void *addr, size_t len, int flags = MS_SYNC);
 338 };
 339
 340 ACE_END_VERSIONED_NAMESPACE_DECL
 341
 342 #if defined (__ACE_INLINE__)
 343 #include "ace/MMAP_Memory_Pool.inl"
 344 #endif /* __ACE_INLINE__ */
 345
 346 #include /**/ "ace/post.h"
 347 #endif /* ACE_MMAP_MEMORY_POOL_H */