Struct mmap_alloc::MapAllocBuilder

pub struct MapAllocBuilder { /* fields omitted */ }

A builder for MapAlloc.

MapAllocBuilder represents the configuration of a MapAlloc. New MapAllocBuilders are constructed using default, and then various other methods are used to set various configuration options.

Memory Permissions

One aspect that can be configured is the permissions of allocated memory - readable, writable, or executable. By default, memory is readable and writable but not executable. Note that not all combinations of permissions are supported on all platforms, and if a particular combination is not supported, then another combination that is no more restrictive than the requested combination will be used. For example, if execute-only permission is requested, but that is not supported, then read/execute, write/execute, or read/write/execute permissions may be used. The only guarantee that is made is that if the requested combination is supported on the runtime platform, then precisely that configuration will be used.

Here are the known limitations with respect to permissions. This list is not guaranteed to be exhaustive:

• Unix: On some platforms, write permission may imply read permission (so write and write/execute are not supported), and read permission may imply execute permission (so read and read/write are not supported).
• Windows:
  • Write permission is not supported; it is implemented as read/write.
  • Write/execute permission is not supported; it is implemented as read/write/execute.

A warning about executable memory

When allocating memory for the purpose of storing executable code, be careful about instruction cache incoherency. Most CPUs keep a cache of recently-executed instructions, and writing to executable memory will often not cause this cache to be invalidated, leading to surprising behavior such as old code being executed even after new code has been written to memory.

In order to avoid this scenario, it is often necessary to explicitly flush the instruction cache before executing newly-written memory. The mechanism to accomplish this differs by system.

Methods

impl MapAllocBuilder

fn build(&self) -> MapAlloc

fn read(self, read: bool) -> MapAllocBuilder

Configures read permission for allocated memory.

read configures whether or not allocated memory will be readable. The default is readable.

See the "Memory Permissions" section of the MapAllocBuilder documentation for more details.

fn write(self, write: bool) -> MapAllocBuilder

Configures write permission for allocated memory.

write configures whether or not allocated memory will be writable. The default is writable.

See the "Memory Permissions" section of the MapAllocBuilder documentation for more details.

fn exec(self, exec: bool) -> MapAllocBuilder

Configures execute permission for allocated memory.

exec configures whether or not allocated memory will be executable. The default is non-executable.

See the "Memory Permissions" section of the MapAllocBuilder documentation for more details.

fn no_write(self) -> MapAllocBuilder

Disables write permission for allocated memory.

no_write makes it so that allocated memory will not be writable. The default is writable.

See the "Memory Permissions" section of the MapAllocBuilder documentation for more details.

fn commit(self, commit: bool) -> MapAllocBuilder

Configures whether alloc returns committed memory.

commit configures whether the memory returned by alloc is already in a committed state. The default is to have memory be returned by alloc uncommitted.

Platform-specific behavior

commit is only supported on Linux and Windows.

fn obj_size(self, obj_size: usize) -> MapAllocBuilder

Sets the object size for the UntypedObjectAlloc implementation.

MapAlloc implements UntypedObjectAlloc. obj_size sets the object size that will be used by that implementation. It defaults to whatever page size is configured for the allocator.

Trait Implementations

impl Default for MapAllocBuilder

fn default() -> MapAllocBuilder

Returns the "default value" for a type.