Struct mappedheap::MappedHeap [−] [src]

pub struct MappedHeap { /* fields omitted */ }

An extensible memory mapped file that keeps track of used and free pages with a simple freelist allocator.

The file will grow whenever necessary. It will always doube in size to make sure resizes are rare.

Example

use mappedheap::MappedHeap;

let mapping = MappedHeap::open("/tmp/test.bin").unwrap();
let page_id = mapping.alloc();
let page_ptr = mapping.page(page_id).unwrap();
// do someting with page_ptr ...
mapping.free(page_id);

Methods

impl MappedHeap
[src]

Opens a file as a MappedHeap.

This will panic if the file is not a valid MappedHeap.

Opens a file as a MappedHeap.

This will atomically create and initialize the file if it doesn't exist.

Retrieves a pointer to a given page by Id, if exists within the file. The mapping is not guaranteed to be contiguous, thus operating out of the bounds of the returned pointer is undefined behavior.

Security note: This only guarantees that the returned pointer points to memory backed by the file (and not some random other location).

Most importantly, it does not protect you from inconsistencies caused by misuse of this API or outside interference (someone else messing with the file), such as:

  • The page is not allocated (or was double-free'd) - it might even contain the freelist.
  • The page is in use concurrently - data races will occur.
  • The page was arbitrarily modified by another application.

By unsafely operating on the returned pointer, it is your sole responsibility to make sure that your code does not violate memory safety!

Panics

  • If the mapping needs to be extended but the syscall fails. Resource exhaustion (memory limits) is the only documented case where this can happen.

Retrieves a reference to a given page by Id, if it exists within the file.

Security note: This only guarantees that the returned reference points to memory backed by the file (and not some random other location).

Most importantly, it does not protect you from inconsistencies caused by misues of this API or outside interference (someone else messing with the file), such as:

  • The page is not allocated (or was double-free'd) - it might even contain the freelist.
  • The page is in use concurrently - data races will occur.
  • The page was arbitrarily modified by another application.

In fact, even if you implement locking (you should!) you are still forced to just blindly assume that no other application (that doesn't respect your locks) is concurrently modifying the file. Whenever this assumption is violated, your your code may invoke undefined behavior.

By unsafely calling this method, it is your sole responsibility to make sure that your code does not violate memory safety!

Panics

  • If T is not exactly page-sized.
  • If the mapping needs to be extended but the syscall fails. Resource exhaustion (memory limits) is the only documented case where this can happen.

Allocates a new page and returns its Id.

This may double the file's size (if necessary).

Security note: Outside interference as well as bugs in your code (see free for details) may corrupt the freelist structure. In that case, while this function will not violate memory safety, its behavior is undefined otherwise.

Panics

  • If the mapping needs to be extended but the syscall fails. Resource exhaustion (memory limits) is the only documented case where this can happen.
  • If the file has to be extended but the syscall fails.
  • May panic if the freelist structure is corrupt.

Frees a page.

Even though neither the mapping nor the file size will ever shrink, the disk space associated with this page may be reclaimed on supported operating and file systems (right now, only Linux is supported, have a look at fallocate(2) for a list of file systems that support hole punching).

Security note: This only checks that the given page exists - nothing else.

Invoking this method on pages that were not previously returned by alloc ("double-free") will corrupt the freelist structure. Concurrent modification by other applications not using this API may have the same effect. In both cases, while this function will not violate memory safety, its behavior is undefined otherwise.

Panics

  • If the given page id is not valid.
  • May panic if the freelist structure is corrupt.