[orthur2]

First and foremost, thank you for assigning this issue to me. Here is the work for review.

This PR implements the six variants of mapped guards for both Mutex and RwLock, as proposed in issue #59:

• MappedMutexGuard (NonOwned, Mutex)
• OwnedMappedMutexGuard (Owned, Mutex)
• MappedRwLockReadGuard (NonOwned, RWLockRead)
• OwnedMappedRwLockReadGuard (Owned, RWLockRead)
• MappedRwLockWriteGuard (NonOwned, RWLockWrite)
• OwnedMappedRwLockWriteGuard (Owned, RWLockWrite)
• and also docs and tests

The difficult parts of the programming process were the strenuous derivation of the Send and Sync traits, as well as managing lifetimes.

The current implementation may have some issues. Please feel free to review the code thoroughly and point out any problems or even the smallest errors. I would be very grateful for your feedback.

It's worth noting that I hesitated for a long time on whether to use try_map() or filter_map(), even though I saw that @tisonkun's PR #58 used try_map(). In my view, the name has a significant impact. While filter_map() is a well-regarded naming choice, and in fact, many designs in the Rust community have evolved from try_map() to filter_map(), I ultimately chose to use try_map. My reasoning is that from a user's perspective, the most critical piece of information is that this function might fail and they need to handle its Result return value. The name filter_map focuses more on the function's internal mechanism, whereas try_map better communicates the operation's external behavior.

Another naming challenge I faced was with the "owned" guards. Although I initially listed them as OwnedMappedMutexGuard, OwnedMappedRwLockWriteGuard, and OwnedMappedRwLockReadGuard when I took the issue. However, during development, I was torn between Owned(MappedMutexGuard) and Mapped(OwnedMutexGuard). If we follow a functional approach of Operation(Object), then Mapped(OwnedMutexGuard) would be the name that best reflects the process. However, I ultimately chose OwnedMappedMutexGuard because I feel it better describes the properties of the Mapped....Guard struct itself. (Owned or NonOwned)

If you have different ideas, please share your views.

What I should mention that I do else:

I moved the read(), try_read(), write(), try_write(), read_owned(), write_owned(), try_read_owned(), and try_write_owned() methods of the RwLock<T> struct from their individual files (read_guard.rs, write_guard.rs, etc.) into mod.rs. I believe it's better to have the method implementations (impl TheType { ... }) in the same file as the type definition (struct TheType { ... }). All these methods belong with the RwLock struct definition.

I fixed a documentation build warning in the mpsc module (unresolved link to UnboundedSender::send,unresolved link to BoundedSender::send, etc.). This was a minor, unrelated warning, but with my preference for keeping things tidy, I fixed it here. I apologize for forgeting creating a separate PR for this, as it is technically out of scope for this issue. Since it was a small change, hope you don't mind me adding it here.

Some related work recommendations for the future:

• Write Lock Downgrading: I considered adding functionality to downgrade a write lock to a read lock when implementing MappedRwLockWriteGuard. However, I noticed the existing WriteGuard didn't have a similar function, so I omitted it. This would be better suited for a separate feature request. After a quick search, I found that both the Rust standard library and Tokio provide downgrade() and even try_downgrade_map.
• Mutex Module Refactoring: It might be a good idea to split the mutex/mod.rs file into separate files like mutexguard.rs, ownedmutexguard.rs, etc., similar to the structure of the rwlock module. I was originally going to do this while working on the issue but decided against it for this PR to avoid extensive code changes that would complicate the review process.

Closes #59

[tisonkun]

Write Lock Downgrading
Mutex Module Refactoring

Both sound reasonable. I just don't have time to implement time before :D

And yes let's keep this further improvement in a follow-up PR.

[tisonkun]

Thanks for your contribution @orthur2! Very detailed description and neat changes. Comments above.

[tisonkun]

LGTM. I push a new commit to updates some coments. Rest is great.

[tisonkun]

Thanks for your contribution!

Write Lock Downgrading
Mutex Module Refactoring

If you're interested in these, welcome to drop new patches. And you can ping me as a reviewer.

[orthur2]

LGTM. I push a new commit to updates some coments. Rest is great.

Thanks a lot for the review and for handling the comments.Glad I could contribute!

[orthur2]

Thanks for your contribution!

Write Lock Downgrading
Mutex Module Refactoring

If you're interested in these, welcome to drop new patches. And you can ping me as a reviewer.

Well, I would like to continue contributing when I have some free time.