MutexGuard re-export does not select an implementation as documented #191

kpreid commented 2026年06月25日 18:21:41 +02:00

According to the documentation located at https://docs.rs/spin/0.12.1/spin/mutex/ :

The Mutex in the root of the crate, can be configured using the ticket_mutex feature. If it’s enabled, TicketMutex and TicketMutexGuard will be re-exported as Mutex and MutexGuard, otherwise the SpinMutex and guard will be re-exported.

However, this is not actually done. The re-export at the root is merely pub use mutex::MutexGuard; and, therefore, has a non-defaulted R type parameter.

Additionally, the links in https://docs.rs/spin/0.12.1/spin/mutex/struct.MutexGuard.html "For more info see..." are broken, because they are URLs for structs but the items linked are type aliases. This could be fixed by deleting the link definitions and using automatic intra-doc links.

According to the documentation located at <https://docs.rs/spin/0.12.1/spin/mutex/> : > The Mutex in the root of the crate, can be configured using the ticket_mutex feature. If it’s enabled, TicketMutex and TicketMutexGuard will be re-exported as Mutex and MutexGuard, otherwise the SpinMutex and guard will be re-exported. However, this is not actually done. The re-export at the root is merely `pub use mutex::MutexGuard;` and, therefore, has a non-defaulted `R` type parameter. Additionally, the links in <https://docs.rs/spin/0.12.1/spin/mutex/struct.MutexGuard.html> "For more info see..." are broken, because they are URLs for `struct`s but the items linked are type aliases. This could be fixed by deleting the link definitions and using automatic intra-doc links.

zesterer commented 2026年06月26日 22:02:06 +02:00

Ah, this looks like a case of incorrect documentation. The feature is actually called use_ticket_mutex - the ticket_mutex by itself only enables the ticket_mutex module, it doesn't switch the default implementation.

The broken links are, I think, a hack around missing rustdoc features that have now existed for a long time.

Thanks for pointing these out. I've pushed up fixes for both documentation issues and they'll be in the next release (whenever that is). Cheers!

Ah, this looks like a case of incorrect documentation. The feature is actually called `use_ticket_mutex` - the `ticket_mutex` by itself only enables the `ticket_mutex` module, it doesn't switch the default implementation. The broken links are, I think, a hack around missing `rustdoc` features that have now existed for a long time. Thanks for pointing these out. I've pushed up fixes for both documentation issues and they'll be in the next release (whenever that is). Cheers!

kpreid commented 2026年06月27日 02:14:19 +02:00

Oh, I see, I was actually misunderstanding what the problem I saw is. The TicketMutex is actually a red herring, unrelated to the upgrade issue that made me read the documentation and see wrong information. What I actually observed is that spin::MutexGuard as of version 0.12 newly has a non-defaulted R type parameter, while spin::Mutex does not; which is not necessarily wrong, but surprising.

That said, the documentation is still inconsistent with the code. As of 10504960a0, it says that

The Mutex in the root of the crate, can be configured using the use_ticket_mutex feature. If it's enabled, TicketMutex and TicketMutexGuard will be re-exported as Mutex and MutexGuard, otherwise the SpinMutex and guard will be re-exported.

but in fact the feature controls a change of the internal implementation of mutex::Mutex, not a change of re-export — which is good API design, but not what is documented.

Oh, I see, I was actually misunderstanding what the problem I saw is. The `TicketMutex` is actually a red herring, unrelated to the upgrade issue that made me read the documentation and see wrong information. What I actually observed is that `spin::MutexGuard` as of version 0.12 newly has a non-defaulted `R` type parameter, while `spin::Mutex` does not; which is not necessarily wrong, but surprising. That said, the documentation is still inconsistent with the code. As of 10504960a030db470b6aa64c4279177264675685, it says that > The `Mutex` in the root of the crate, can be configured using the `use_ticket_mutex` feature. If it's enabled, `TicketMutex` and `TicketMutexGuard` will be re-exported as `Mutex` and `MutexGuard`, otherwise the `SpinMutex` and guard will be re-exported. but in fact the feature controls a change of the internal implementation of `mutex::Mutex`, not a change of re-export — which is good API design, but not what is documented.

zesterer commented 2026年06月27日 15:45:06 +02:00

Ah, good point. I've fixed those issues now (and the same for a few other cases). Sorry about the confusion.

Argh, I need to find a free weekend to go over the whole crate with a fine-toothed comb and fix up any additional issues like this.

I appreciate you opening the issue!

Ah, good point. I've fixed those issues now (and the same for a few other cases). Sorry about the confusion. Argh, I need to find a free weekend to go over the whole crate with a fine-toothed comb and fix up any additional issues like this. I appreciate you opening the issue!