Added examples for anonymous() and file()

[omh1280]

For #34
Added examples for anonymous() and file().

Please let me know if these look OK! I'll write examples for the other functions if so.

I added ? to all of the examples according to the API guidelines.

Ottavio

[omh1280]

CI is failing because of ?, but I think it's important to include in the example docs.

[danburkert]

I think it's important to include in the example docs.

Yah I agree. It should be possible to run only the non-doc tests using cargo test --lib, but it may require some surgery to ci/script.sh to figure out the rustc version and do a special test.

[brson]

Thanks @omh1280 !

[omh1280]

No problem :) I'll work on the rest of the public functions now

[omh1280]

Fixes #34

Just rebased (hope that's ok) and squashed all of the commits into one.

Added a bunch of examples. Honestly, it became really hard to be creative in every example, but there is now a framework for people to add creativity to the examples :)

How's it look?

P.S. The tests will fail on CI because of ?, but they all pass on my machine.

[danburkert]

Thanks! I just fixed up the CI scripts so that examples won't be compiled with rustc 1.8.0. If you can rebase over them, the build should go green.

[danburkert]

Thanks! I just fixed up the CI scripts so that examples won't be compiled with rustc 1.8.0. If you can rebase over them, the build should go green.

[danburkert]

Just curious - does this change the rendered output at all?

[danburkert]

Perhaps this should use unwrap_err instead of ? just to make it doubly-clear that it's supposed to fail? That would also allow the main() method to use unwrap, so that it's more tested.

[omh1280]

So, quick question: what is an allowable set_protection? Because apparently going from ReadCopy to ReadWrite gives an error:
code: 87, message: "The parameter is incorrect"

But I can't put in a ReadWrite to ReadCopy example because it doesn't have permissions to open README.md. (Unless the doc test is no_run, but that defeats the purpose)

Also, as far as I can tell, there is no test for set_protection, so I don't have anything to work off of (and I don't really understand why a user would change the protection of a mutable mmap).

Thanks!

[danburkert]

It should be possible to go from Read to ReadWrite using set_protection, but it requires the file to originally be opened with read + write permissions (e.g. OpenOptions::new().read(true).write(true).open("foo.txt")).

But I can't put in a ReadWrite to ReadCopy example because it doesn't have permissions to open README.md. (Unless the doc test is no_run, but that defeats the purpose)

Yah, it's not possible to remap from a SHARED mmap to a PRIVATE mmap, that's one of the reasons I think we're going to remove the protections system in favor of specific methods (see my recent comment on #33).

[omh1280]

Oh cool, I forgot about OpenOptions.

Unfortunately, the map_mut function denies Read protection with "Invalid protection for a mutable mapping."

[danburkert]

Yah, again this is a great reason why Protection should be removed. I'm going to work on that. I'd suggest skipping set_protection in this example for now, or instead making the example use make_read_only.

[danburkert]

See #46 for what the API might look like. I'm going to merge yours first since that PR will take a while to land, so don't worry about potentia conflicts.

[danburkert]

I think it would be better to have these examples return io::Result<T> instead of Result<T, Box<Error>>. I think having the concrete return type of the methods is more instructive, especially when it's a common type like io::Error.

[omh1280]

Great point

[danburkert]

Thanks again!