MMAP_Memory_Pool.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file     MMAP_Memory_Pool.h
00006  *
00007  *  $Id: MMAP_Memory_Pool.h 78476 2007-05-24 07:55:50Z johnnyw $
00008  *
00009  *  @author Dougls C. Schmidt <schmidt@cs.wustl.edu>
00010  *  @author Prashant Jain <pjain@cs.wustl.edu>
00011  */
00012 //=============================================================================
00013 
00014 #ifndef ACE_MMAP_MEMORY_POOL_H
00015 #define ACE_MMAP_MEMORY_POOL_H
00016 
00017 #include /**/ "ace/pre.h"
00018 
00019 #include /**/ "ace/ACE_export.h"
00020 
00021 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00022 # pragma once
00023 #endif /* ACE_LACKS_PRAGMA_ONCE */
00024 
00025 #include "ace/ACE.h"
00026 #include "ace/Event_Handler.h"
00027 #include "ace/Sig_Handler.h"
00028 #include "ace/Mem_Map.h"
00029 
00030 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00031 
00032 /**
00033  * @class ACE_MMAP_Memory_Pool_Options
00034  *
00035  * @brief Helper class for MMAP Memory Pool constructor options.
00036  *
00037  * This should be a nested class, but that breaks too many
00038  * compilers.
00039  */
00040 class ACE_Export ACE_MMAP_Memory_Pool_Options
00041 {
00042 public:
00043   enum
00044   {
00045     /**
00046      * The base address from the first call to mmap will be used for subsequent
00047      * calls to mmap.
00048      */
00049     FIRSTCALL_FIXED = 0,
00050 
00051     /**
00052      * The base address specified in base_addr will be used in all calls to
00053      * mmap.
00054      */
00055     ALWAYS_FIXED = 1,
00056 
00057     /**
00058      * The base address will be selected by the OS for each call to mmap.
00059      * Caution should be used with this mode since a call that requires the
00060      * backing store to grow may change pointers that are cached by the
00061      * application.
00062      */
00063     NEVER_FIXED = 2
00064   };
00065 
00066   // = Initialization method.
00067   ACE_MMAP_Memory_Pool_Options (const void *base_addr = ACE_DEFAULT_BASE_ADDR,
00068                                 int use_fixed_addr = ALWAYS_FIXED,
00069                                 int write_each_page = 1,
00070                                 size_t minimum_bytes = 0,
00071                                 u_int flags = 0,
00072                                 int guess_on_fault = 1,
00073                                 LPSECURITY_ATTRIBUTES sa = 0,
00074                                 mode_t file_mode = ACE_DEFAULT_FILE_PERMS,
00075                                 bool unique_ = false);
00076 
00077   /// Base address of the memory-mapped backing store.
00078   const void *base_addr_;
00079 
00080   /**
00081    * Determines whether we set @c base_addr_ or if mmap(2) selects it
00082    * FIRSTCALL_FIXED The base address from the first call to mmap
00083    *                 will be used for subsequent calls to mmap
00084    * ALWAYS_FIXED    The base address specified in base_addr will be
00085    *                 used in all calls to mmap.
00086    * NEVER_FIXED     The base address will be selected by the OS for
00087    *                 each call to mmap. Caution should be used with
00088    *                 this mode since a call that requires the backing
00089    *                 store to grow may change pointers that are
00090    *                 cached by the application.
00091    */
00092   int use_fixed_addr_;
00093 
00094   /// Should each page be written eagerly to avoid surprises later
00095   /// on?
00096   int write_each_page_;
00097 
00098   /// What the minimim bytes of the initial segment should be.
00099   size_t minimum_bytes_;
00100 
00101   /// Any special flags that need to be used for @c mmap.
00102   u_int flags_;
00103 
00104   /**
00105    * Try to remap without knowing the faulting address.  This
00106    * parameter is ignored on platforms that know the faulting address
00107    * (UNIX with SI_ADDR and Win32).
00108    */
00109   bool guess_on_fault_;
00110 
00111   /// Pointer to a security attributes object.  Only used on NT.
00112   LPSECURITY_ATTRIBUTES sa_;
00113 
00114   /// File mode for mmaped file, if it is created.
00115   mode_t file_mode_;
00116 
00117   /// Do we want an unique backing store name?
00118   bool unique_;
00119 
00120 private:
00121   // Prevent copying
00122   ACE_MMAP_Memory_Pool_Options (const ACE_MMAP_Memory_Pool_Options &);
00123   ACE_MMAP_Memory_Pool_Options &operator= (const ACE_MMAP_Memory_Pool_Options &);
00124 };
00125 
00126 /**
00127  * @class ACE_MMAP_Memory_Pool
00128  *
00129  * @brief Make a memory pool that is based on @c mmap(2).  This
00130  * implementation allows memory to be shared between processes.
00131  */
00132 class ACE_Export ACE_MMAP_Memory_Pool : public ACE_Event_Handler
00133 {
00134 public:
00135   typedef ACE_MMAP_Memory_Pool_Options OPTIONS;
00136 
00137   // = Initialization and termination methods.
00138 
00139   /// Initialize the pool.
00140   ACE_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0,
00141                         const OPTIONS *options = 0);
00142 
00143   /// Destructor.
00144   virtual ~ACE_MMAP_Memory_Pool (void);
00145 
00146   /// Ask system for initial chunk of shared memory.
00147   virtual void *init_acquire (size_t nbytes,
00148                               size_t &rounded_bytes,
00149                               int &first_time);
00150 
00151   /**
00152    * Acquire at least @a nbytes from the memory pool. @a rounded_bytes
00153    * is the actual number of bytes allocated.  Also acquires an
00154    * internal semaphore that ensures proper serialization of
00155    * ACE_MMAP_Memory_Pool initialization across processes.
00156    */
00157   virtual void *acquire (size_t nbytes,
00158                          size_t &rounded_bytes);
00159 
00160   /// Instruct the memory pool to release all of its resources.
00161   virtual int release (int destroy = 1);
00162 
00163   /// Sync the memory region to the backing store starting at
00164   /// @c this->base_addr_.
00165   virtual int sync (size_t len, int flags = MS_SYNC);
00166 
00167   /// Sync the memory region to the backing store starting at
00168   /// @c this->base_addr_.  Will sync as much as the backing file
00169   /// allows.
00170   virtual int sync (int flags = MS_SYNC);
00171 
00172   /// Sync the memory region to the backing store starting at @a addr.
00173   virtual int sync (void *addr, size_t len, int flags = MS_SYNC);
00174 
00175   /**
00176    * Change the protection of the pages of the mapped region to @a prot
00177    * starting at <this->base_addr_> up to @a len bytes.  If @a len == -1
00178    * then change protection of all pages in the mapped region.
00179    */
00180   virtual int protect (size_t len, int prot = PROT_RDWR);
00181 
00182   /**
00183    * Change the protection of all the pages of the mapped region to @a prot
00184    * starting at <this->base_addr_>.
00185    */
00186   virtual int protect (int prot = PROT_RDWR);
00187 
00188   /// Change the protection of the pages of the mapped region to @a prot
00189   /// starting at @a addr up to @a len bytes.
00190   virtual int protect (void *addr, size_t len, int prot = PROT_RDWR);
00191 
00192 #if defined (ACE_WIN32)
00193   /**
00194    * Win32 Structural exception selector.  The return value decides
00195    * how to handle memory pool related structural exceptions.  Returns
00196    * 1, 0, or , -1.
00197    */
00198   virtual int seh_selector (void *);
00199 #endif /* ACE_WIN32 */
00200 
00201   /**
00202    * Try to extend the virtual address space so that @a addr is now
00203    * covered by the address mapping.  The method succeeds and returns
00204    * 0 if the backing store has adequate memory to cover this address.
00205    * Otherwise, it returns -1.  This method is typically called by a
00206    * UNIX signal handler for SIGSEGV or a Win32 structured exception
00207    * when another process has grown the backing store (and its
00208    * mapping) and our process now incurs a fault because our mapping
00209    * isn't in range (yet).
00210    */
00211   virtual int remap (void *addr);
00212 
00213   /// Return the base address of this memory pool.
00214   virtual void *base_addr (void) const;
00215 
00216   /// Dump the state of an object.
00217   virtual void dump (void) const;
00218 
00219   /// Get reference to underlying ACE_Mem_Map object.
00220   ACE_Mem_Map const & mmap (void) const;
00221 
00222   /// Get reference to underlying ACE_Mem_Map object.
00223   ACE_Mem_Map & mmap (void);
00224 
00225   /// Declare the dynamic allocation hooks.
00226   ACE_ALLOC_HOOK_DECLARE;
00227 
00228 protected:
00229   /// Implement the algorithm for rounding up the request to an
00230   /// appropriate chunksize.
00231   virtual size_t round_up (size_t nbytes);
00232 
00233   /// Compute the new @a map_size of the backing store and commit the
00234   /// memory.
00235   virtual int commit_backing_store_name (size_t rounded_bytes,
00236                                          size_t & map_size);
00237 
00238   /// Memory map the file up to @a map_size bytes.
00239   virtual int map_file (size_t map_size);
00240 
00241   /// Handle SIGSEGV and SIGBUS signals to remap shared memory
00242   /// properly.
00243   virtual int handle_signal (int signum, siginfo_t *, ucontext_t *);
00244 
00245   /// Handles SIGSEGV.
00246   ACE_Sig_Handler signal_handler_;
00247 
00248   /// Memory-mapping object.
00249   ACE_Mem_Map mmap_;
00250 
00251   /**
00252    * Base of mapped region.  If this has the value of 0 then the OS is
00253    * free to select any address to map the file, otherwise this value
00254    * is what the OS must try to use to mmap the file.
00255    */
00256   void *base_addr_;
00257 
00258   /// Must we use the @c base_addr_ or can we let mmap(2) select it?
00259   int use_fixed_addr_;
00260 
00261   /// Flags passed into <ACE_OS::mmap>.
00262   int flags_;
00263 
00264   /// Should we write a byte to each page to forceably allocate memory
00265   /// for this backing store?
00266   int write_each_page_;
00267 
00268   /// What the minimum bytes of the initial segment should be.
00269   size_t minimum_bytes_;
00270 
00271   /// Name of the backing store where the shared memory pool is kept.
00272   ACE_TCHAR backing_store_name_[MAXPATHLEN + 1];
00273 
00274   /**
00275    * Try to remap without knowing the faulting address.  This
00276    * parameter is ignored on platforms that know the faulting address
00277    * (UNIX with SI_ADDR and Win32).
00278    */
00279   bool guess_on_fault_;
00280 
00281   /// Security attributes object, only used on NT.
00282   LPSECURITY_ATTRIBUTES sa_;
00283 
00284   /// Protection mode for mmaped file.
00285   mode_t file_mode_;
00286 };
00287 
00288 /**
00289  * @class ACE_Lite_MMAP_Memory_Pool
00290  *
00291  * @brief Make a ``lighter-weight'' memory pool based ACE_Mem_Map.
00292  *
00293  * This implementation allows memory to be shared between
00294  * processes.  However, unlike the ACE_MMAP_Memory_Pool
00295  * the <sync> methods are no-ops, which means that we don't pay
00296  * for the price of flushing the memory to the backing store on
00297  * every update.  Naturally, this trades off increased
00298  * performance for less reliability if the machine crashes.
00299  */
00300 class ACE_Export ACE_Lite_MMAP_Memory_Pool : public ACE_MMAP_Memory_Pool
00301 {
00302 public:
00303   /// Initialize the pool.
00304   ACE_Lite_MMAP_Memory_Pool (const ACE_TCHAR *backing_store_name = 0,
00305                              const OPTIONS *options = 0);
00306 
00307   /// Destructor.
00308   virtual ~ACE_Lite_MMAP_Memory_Pool (void);
00309 
00310   /// Overwrite the default sync behavior with no-op
00311   virtual int sync (size_t len, int flags = MS_SYNC);
00312 
00313   /// Overwrite the default sync behavior with no-op
00314   virtual int sync (int flags = MS_SYNC);
00315 
00316   /// Overwrite the default sync behavior with no-op
00317   virtual int sync (void *addr, size_t len, int flags = MS_SYNC);
00318 };
00319 
00320 ACE_END_VERSIONED_NAMESPACE_DECL
00321 
00322 #if defined (__ACE_INLINE__)
00323 #include "ace/MMAP_Memory_Pool.inl"
00324 #endif /* __ACE_INLINE__ */
00325 
00326 #include /**/ "ace/post.h"
00327 #endif /* ACE_MMAP_MEMORY_POOL_H */

Generated on Sun Jan 27 12:05:32 2008 for ACE by doxygen 1.3.6