---
name: "ACE_MMAP_Memory_Pool"
section: "3"
platform: "linux"
package: "libace-doc"
version: "5.0.7-4"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/ACE_MMAP_Memory_Pool"
---

# ACE\_MMAP\_Memory\_Pool(3)

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

## NAME

ACE\_MMAP\_Memory\_Pool -  Make a memory pool that is based on [mmap(2)](/mmap/2.md).  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