## NAME

ACE_MMAP_Memory_Pool - Make a memory pool that is based on `mmap(2)`. This implementation allows memory to be shared between processes.

## SYNOPSIS

    #include <ace/ACE_Memory_Pool.h>

    class ACE_MMAP_Memory_Pool : public ACE_Event_Handler
    {
      public:
        typedef ACE_MMAP_Memory_Pool_Options OPTIONS;
        ACE_MMAP_Memory_Pool (
            LPCTSTR backing_store_name = 0,
            const OPTIONS *options = 0
            );
        virtual ~ACE_MMAP_Memory_Pool (void);
        virtual void *init_acquire (
            size_t nbytes,
            size_t &rounded_bytes,
            int &first_time
            );
        virtual void *acquire (size_t nbytes, size_t &rounded_bytes);
        virtual int release (void);
        virtual int sync (ssize_t len = -1, int flags = MS_SYNC);
        virtual int sync (void *addr, size_t len, int flags = MS_SYNC);
        virtual int protect (ssize_t len = -1, int prot = PROT_RDWR);
        virtual int protect (
            void *addr,
            size_t len,
            int prot = PROT_RDWR
            );
        virtual int remap (void *addr);
        virtual void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      protected:
        virtual size_t round_up (size_t nbytes);
        virtual int commit_backing_store_name (
            size_t rounded_bytes,
            off_t &map_size
            );
        virtual int map_file (off_t map_size);
        virtual int handle_signal (int signum, siginfo_t *, ucontext_t *);
        ACE_Sig_Handler signal_handler_;
        ACE_Mem_Map mmap_;
        void *base_addr_;
        int flags_;
        int write_each_page_;
        off_t minimum_bytes_;
        TCHAR backing_store_name_[MAXPATHLEN + 1];
        int guess_on_fault_;
        LPSECURITY_ATTRIBUTES sa_;
    };

## Initialization and termination methods.

    ACE_MMAP_Memory_Pool (
        LPCTSTR backing_store_name = 0,
        const OPTIONS *options = 0
        );

Initialize the pool.

    virtual ~ACE_MMAP_Memory_Pool (void);

    virtual void *init_acquire (
        size_t nbytes,
        size_t &rounded_bytes,
        int &first_time
        );

Ask system for initial chunk of shared memory.

    virtual void *acquire (size_t nbytes, size_t &rounded_bytes);

Acquire at least `nbytes` from the memory pool. `rounded_bytes` is the actual number of bytes allocated. Also acquires an internal semaphore that ensures proper serialization of `ACE_MMAP_Memory_Pool` initialization across processes.

    virtual int release (void);

Instruct the memory pool to release all of its resources.

    virtual int sync (ssize_t len = -1, int flags = MS_SYNC);

Sync the memory region to the backing store starting at `this-`base_addr_.

    virtual int sync (void *addr, size_t len, int flags = MS_SYNC);

Sync the memory region to the backing store starting at `addr_`.

    virtual int protect (ssize_t len = -1, int prot = PROT_RDWR);

Change the protection of the pages of the mapped region to `prot` starting at `this-`base_addr_ up to `len` bytes. If `len` == -1 then change protection of all pages in the mapped region.

    virtual int protect (void *addr, size_t len, int prot = PROT_RDWR);

Change the protection of the pages of the mapped region to `prot` starting at `addr` up to `len` bytes.

    virtual int remap (void *addr);

Try to extend the virtual address space so that `addr` is now covered by the address mapping. The method succeeds and returns 0 if the backing store has adequate memory to cover this address. Otherwise, it returns -1. This method is typically called by a UNIX signal handler for SIGSEGV or a Win32 structured exception when another process has grown the backing store (and its mapping) and our process now incurs a fault because our mapping isn't in range (yet).

    virtual void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## Implement the algorithm for rounding up the request to an

appropriate chunksize.

    virtual size_t round_up (size_t nbytes);

    virtual int commit_backing_store_name (
        size_t rounded_bytes,
        off_t &map_size
        );

Compute the new `map_size` of the backing store and commit the memory.

    virtual int map_file (off_t map_size);

Memory map the file up to `map_size` bytes.

    virtual int handle_signal (int signum, siginfo_t *, ucontext_t *);

Handle SIGSEGV and SIGBUS signals to remap shared memory properly.

    ACE_Sig_Handler signal_handler_;

Handles SIGSEGV.

    ACE_Mem_Map mmap_;

Memory-mapping object.

    void *base_addr_;

Base of mapped region. If this has the value of 0 then the OS is free to select any address to map the file, otherwise this value is what the OS must try to use to mmap the file.

    int flags_;

Flags passed into `ACE_OS::mmap`.

    int write_each_page_;

Should we write a byte to each page to forceably allocate memory for this backing store?

    off_t minimum_bytes_;

What the minimum bytes of the initial segment should be.

    TCHAR backing_store_name_[MAXPATHLEN + 1];

Name of the backing store where the shared memory pool is kept.

    int guess_on_fault_;

Try to remap without knowing the faulting address. This parameter is ignored on platforms that know the faulting address (UNIX with SI_ADDR and Win32).

    LPSECURITY_ATTRIBUTES sa_;

Security attributes object, only used on NT.

## AUTHOR

Doug Schmidt and Prashant Jain

## LIBRARY

ace