ACE/ace/MMAP_Memory_Pool.h

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