Generic mutability crate published -- looking for contributions

announcements
1

I'm happy to announce that I published the first version of generic-mutability, which allows library authors to create APIs that are generic over mutability (e.g. unique vs shared references).

If you haven't heard of it, generic mutability allows one (among other things) to write a pair of functions of the form

fn get<'a>(&'a T, ...) -> &'a U
fn get_mut<'a>(&'a mut T, ...) -> &'a mut U

as a single function

fn get_gen<'a, M: Mutability>(GenRef<'a, M, T>, ...) -> GenRef<'a, M, U>

This crate provides a GenRef type that makes this possible, with the long term goal of becoming a language feature one day.

It is still experimental, so breaking changes can still happen, but the implementation is complete and usable.

However, I feel like I reached the limit to where I could push this project alone, so I would like to ask for your feedback and help on the following things:

  • Review

    • unsafe!

      The project uses (and requires) unsafe code. While I'm relatively sure that the core idea is sound, I need more eyeballs to make sure that all implementations are sound including all edge cases, too. (After reading a lot about unsafe, my experience is that there is always one more corner case that I didn't think of.)

    • Documentation

      Please ask me stuff that is unclear or difficult to understand, so I can improve the docs to make it more accessible.

    • API design

      Is the API easily usable? Are there any improvements you can think of? What color should the bikeshed be? I'll create a few issues on GitHub about things I'd like to discuss, and feel free to create more.

    • Optimizations

      All of the crate's functionality should be zero-cost, but it relies on compiler optimizations. I'm not sure if the compiler can actually optimize everything away.

  • Contribute

    • Tests, tests, tests!

      I suck at writing tests. I wrote a few, but I feel like I would need a lot more! But I don't really know how to go about it. So if you'd write some tests (or help me write more), I'd greatly appreciate it!

    • std interface

      To make this crate easier to use, I'm planning to create a separate crate that contains extension traits, structs & functions that help this crate interface with std and core APIs better, where applicable. Once I created the other crate, I'm looking for contributions on this one too.

2

i don't think you need to put a doc comment on impl blocks just describing the bounds of the impl.

it could be mildly useful to put those comments on the methods themselves, since it is otherwise somewhat easy to miss them, expecially in large impl blocks.

i think saying they are "not available in generic contexts" is misleading, since those methods are still genetic over T. saying they are not available for references with generic mutability would be more accurate.

3

I clarified the doc comments, they were indeed a bit confusing. I didn't move them onto the methods, because then they would hide the methods' own documentation, which I think would harm more than help.

With that said, I agree that they are not very important or useful, but I didn't want to delete them, because I see no harm in keeping them and they might as well help someone. (Once I had a case with another crate where I wasn't able to call a method, I couldn't figure out why, and only later noticed that it was not implemented generically.)

4

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.