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   ACE_MMAP_Memory_Pool_Options (const ACE_MMAP_Memory_Pool_Options &) = delete;
 124   ACE_MMAP_Memory_Pool_Options &operator= (const ACE_MMAP_Memory_Pool_Options &) = delete;
 125 };
 126
 127 /**
 128  * @class ACE_MMAP_Memory_Pool
 129  *
 130  * @brief Make a memory pool that is based on @c mmap(2).  This
 131  * implementation allows memory to be shared between processes.
 132  */
 133 class ACE_Export ACE_MMAP_Memory_Pool : public ACE_Event_Handler
 134 {
 135 public:
 136   typedef ACE_MMAP_Memory_Pool_Options OPTIONS;
 137
 138   /// Initialize the pool.
 139   ACE_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0,
 140                         const OPTIONS *options = 0);
 141
 142   /// Destructor.
 143   virtual ~ACE_MMAP_Memory_Pool ();
 144
 145   /// Ask system for initial chunk of shared memory.
 146   virtual void *init_acquire (size_t nbytes,
 147                               size_t &rounded_bytes,
 148                               int &first_time);
 149
 150   /**
 151    * Acquire at least @a nbytes from the memory pool. @a rounded_bytes
 152    * is the actual number of bytes allocated.  Also acquires an
 153    * internal semaphore that ensures proper serialization of
 154    * ACE_MMAP_Memory_Pool initialization across processes.
 155    */
 156   virtual void *acquire (size_t nbytes,
 157                          size_t &rounded_bytes);
 158
 159   /// Instruct the memory pool to release all of its resources.
 160   virtual int release (int destroy = 1);
 161
 162   /// Sync the memory region to the backing store starting at
 163   /// @c this->base_addr_.
 164   virtual int sync (size_t len, int flags = MS_SYNC);
 165
 166   /// Sync the memory region to the backing store starting at
 167   /// @c this->base_addr_.  Will sync as much as the backing file
 168   /// allows.
 169   virtual int sync (int flags = MS_SYNC);
 170
 171   /// Sync the memory region to the backing store starting at @a addr.
 172   virtual int sync (void *addr, size_t len, int flags = MS_SYNC);
 173
 174   /**
 175    * Change the protection of the pages of the mapped region to @a prot
 176    * starting at @c this->base_addr_ up to @a len bytes.  If @a len == -1
 177    * then change protection of all pages in the mapped region.
 178    */
 179   virtual int protect (size_t len, int prot = PROT_RDWR);
 180
 181   /**
 182    * Change the protection of all the pages of the mapped region to @a prot
 183    * starting at @c this->base_addr_.
 184    */
 185   virtual int protect (int prot = PROT_RDWR);
 186
 187   /// Change the protection of the pages of the mapped region to @a prot
 188   /// starting at @a addr up to @a len bytes.
 189   virtual int protect (void *addr, size_t len, int prot = PROT_RDWR);
 190
 191 #if defined (ACE_WIN32)
 192   /**
 193    * Win32 Structural exception selector.  The return value decides
 194    * how to handle memory pool related structural exceptions.  Returns
 195    * 1, 0, or , -1.
 196    */
 197   virtual int seh_selector (void *);
 198 #endif /* ACE_WIN32 */
 199
 200   /**
 201    * Try to extend the virtual address space so that @a addr is now
 202    * covered by the address mapping.  The method succeeds and returns
 203    * 0 if the backing store has adequate memory to cover this address.
 204    * Otherwise, it returns -1.  This method is typically called by a
 205    * UNIX signal handler for SIGSEGV or a Win32 structured exception
 206    * when another process has grown the backing store (and its
 207    * mapping) and our process now incurs a fault because our mapping
 208    * isn't in range (yet).
 209    */
 210   virtual int remap (void *addr);
 211
 212   /// Return the base address of this memory pool.
 213   virtual void *base_addr () const;
 214
 215   /// Dump the state of an object.
 216   virtual void dump () const;
 217
 218   /// Get reference to underlying ACE_Mem_Map object.
 219   ACE_Mem_Map const & mmap () const;
 220
 221   /// Get reference to underlying ACE_Mem_Map object.
 222   ACE_Mem_Map & mmap ();
 223
 224   /// Declare the dynamic allocation hooks.
 225   ACE_ALLOC_HOOK_DECLARE;
 226
 227 protected:
 228   /// Implement the algorithm for rounding up the request to an
 229   /// appropriate chunksize.
 230   virtual size_t round_up (size_t nbytes);
 231
 232   /// Compute the new @a map_size of the backing store and commit the
 233   /// memory.
 234   virtual int commit_backing_store_name (size_t rounded_bytes,
 235                                          size_t & map_size);
 236
 237   /// Memory map the file up to @a map_size bytes.
 238   virtual int map_file (size_t map_size);
 239
 240 #if !defined (ACE_WIN32)
 241   /**
 242    * Handle SIGSEGV and SIGBUS signals to remap memory properly.  When a
 243    * process reads or writes to non-mapped memory a signal (SIGBUS or
 244    * SIGSEGV) will be triggered.  At that point, the ACE_Sig_Handler
 245    * (which is part of the ACE_Reactor) will catch the signal and
 246    * dispatch the handle_signal() method defined here.  If the SIGSEGV
 247    * signal occurred due to the fact that the mapping wasn't up to date
 248    * with respect to the backing store, the handler method below will
 249    * update the mapping accordingly. When the signal handler returns,
 250    * the instruction should be restarted and the operation should work.
 251    */
 252   virtual int handle_signal (int signum, siginfo_t *, ucontext_t *);
 253 #endif
 254
 255 #if !defined (ACE_WIN32)
 256   /// Handles SIGSEGV.
 257   ACE_Sig_Handler signal_handler_;
 258 #endif
 259
 260   /// Memory-mapping object.
 261   ACE_Mem_Map mmap_;
 262
 263   /**
 264    * Base of mapped region.  If this has the value of 0 then the OS is
 265    * free to select any address to map the file, otherwise this value
 266    * is what the OS must try to use to mmap the file.
 267    */
 268   void *base_addr_;
 269
 270   /// Must we use the @c base_addr_ or can we let mmap(2) select it?
 271   int use_fixed_addr_;
 272
 273   /// Flags passed into ACE_OS::mmap().
 274   int flags_;
 275
 276   /// Should we write a byte to each page to forceably allocate memory
 277   /// for this backing store?
 278   bool write_each_page_;
 279
 280   /// What the minimum bytes of the initial segment should be.
 281   size_t minimum_bytes_;
 282
 283   /// Name of the backing store where the shared memory pool is kept.
 284   ACE_TCHAR backing_store_name_[MAXPATHLEN + 1];
 285
 286   /**
 287    * Try to remap without knowing the faulting address.  This
 288    * parameter is ignored on platforms that know the faulting address
 289    * (UNIX with SI_ADDR and Win32).
 290    */
 291   bool guess_on_fault_;
 292
 293   /// Security attributes object, only used on NT.
 294   LPSECURITY_ATTRIBUTES sa_;
 295
 296   /// Protection mode for mmaped file.
 297   mode_t file_mode_;
 298
 299   /// Should we install a signal handler
 300   bool install_signal_handler_;
 301 };
 302
 303 /**
 304  * @class ACE_Lite_MMAP_Memory_Pool
 305  *
 306  * @brief Make a ``lighter-weight'' memory pool based ACE_Mem_Map.
 307  *
 308  * This implementation allows memory to be shared between
 309  * processes.  However, unlike the ACE_MMAP_Memory_Pool
 310  * the @c sync methods are no-ops, which means that we don't pay
 311  * for the price of flushing the memory to the backing store on
 312  * every update.  Naturally, this trades off increased
 313  * performance for less reliability if the machine crashes.
 314  */
 315 class ACE_Export ACE_Lite_MMAP_Memory_Pool : public ACE_MMAP_Memory_Pool
 316 {
 317 public:
 318   /// Initialize the pool.
 319   ACE_Lite_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0,
 320                              const OPTIONS *options = 0);
 321
 322   /// Destructor.
 323   virtual ~ACE_Lite_MMAP_Memory_Pool ();
 324
 325   /// Overwrite the default sync behavior with no-op
 326   virtual int sync (size_t len, int flags = MS_SYNC);
 327
 328   /// Overwrite the default sync behavior with no-op
 329   virtual int sync (int flags = MS_SYNC);
 330
 331   /// Overwrite the default sync behavior with no-op
 332   virtual int sync (void *addr, size_t len, int flags = MS_SYNC);
 333
 334   /// Declare the dynamic allocation hooks.
 335   ACE_ALLOC_HOOK_DECLARE;
 336 };
 337
 338 ACE_END_VERSIONED_NAMESPACE_DECL
 339
 340 #if defined (__ACE_INLINE__)
 341 #include "ace/MMAP_Memory_Pool.inl"
 342 #endif /* __ACE_INLINE__ */
 343
 344 #include /**/ "ace/post.h"
 345 #endif /* ACE_MMAP_MEMORY_POOL_H */