Documentation / user guide

[dhardy]

In my opinion, as someone who knows very little about the subject of memory-mapped files, quite a bit more documentation would be useful. This mostly isn't specific to this crate, but having the documentation in one place (ideally within the module documentation) would make the topic easier to learn.

• What are the main use-cases vs non-memory mapped files — performance, memory usage and behaviour differences with read-only and read-write usage. (E.g. is it useful when reading a file sequentially or only when seeking?)
• What are the main costs of mem-mapped files: presumably opening, reading a page, and flushing changes?
• Are there any guarantees when a memory-mapped file is read and modified by another process — e.g. if the writes are only appends, are reads safe? Is it OS-specific?
• Can mem-mapped files be locked by the OS? This may be a separate topic, but pointers welcome.
• How does paging work: entirely automatically in response to pointer dereferences? What's the page size (always 4kB?) & how should applications best allocate file memory to take advantage?

[danburkert]

I have somewhat mixed feelings about this. More documentation is always good, but it's a fine line between documenting the crate and re-writing system man pages.

For what it's worth, my opinion is that there are very few use cases which justify using file-backed memory maps. The trade-offs of mmap vs the conventional file API are subtle and widely misunderstood.

[burdges]

I suppose optimal mmap use cases even change depending upon whether your storage is backed by an HDD or an SSD or one of those new Intel flash things. It's possible to add references to a couple good outside resources, like a good blog post.

[PSeitz]

Is it safe to read from multiple threads? (std::fs::File e.g. is not thread-safe)

[setharnold]

It'd be nice if the docs could describe why some functions have been marked unsafe.

Thanks

[shepmaster]

Seconding the concerns about documenting unsafety. It would be good to document what the caller needs to ensure to keep the program memory safe.

[newpavlov]

+1 for better explanation of unsafe.

If I understand correctly creation of memory mapped buffer is unsafe primary due the ability to create shared mutable memory. But what about using only immutable Mmaps only (e.g. for reading files), is it safe? If so, shouldn't creation of Mmap::map be safe and in turn Mmap::make_mut become unsafe?

[burdges]

I think MAP_ANONYMOUS behave like allocations, so safe even for writing. It's clear MAP_PRIVATE protects readers from your writes, but it's less clear if others could still modify your pages before you read them yourself. And MAP_SHARED would probably never be safe even if read only for the current process.