StephanvanSchaik / mmap-rs

A cross-platform and safe Rust API to create and manage memory mappings in the virtual address space of the calling process.
Apache License 2.0
61 stars 17 forks source link

Add comment documenting the lack of compatiblity of the `STACK` flag on non-unix platforms. #19

Closed manon-traverse closed 1 year ago

manon-traverse commented 1 year ago

The STACK flag is only compatible with unix compatible platforms, but was not documented. This PR adds documentation so it is immediately clear to the user that this can only be used on UNIX platforms.

Open questions:

StephanvanSchaik commented 1 year ago

Thanks for clarifying the documentation for MmapFlags::STACK.

Note that this flag is also a no-op on Linux, so in that sense having it be a no-op on Microsoft Windows also makes sense. Maybe it makes sense to clarify this in the documentation too, since this also applies to flags such as MmapFlags::NO_CORE_DUMP and MmapFlags::TRANSPARENT_HUGE_PAGES.

Hiding those flags on specific platforms would make the API a bit more tedious to use imo. For certain flags, it may make sense for MmapOptions::map() and friends to return an error, though (e.g. MmapFlags::HUGE_PAGES), since that is what happens on platforms where the request cannot be honored anyway. However, these functions generally shouldn't panic, since in this case the user should be able to fallback to requesting a memory mapping without the offending flags, rather than have their code fail at run-time on a specific platform.