embassy-sync: add lock_mut to blocking_mutex::Mutex

[avsaase]

This adds a lock_mut method to blocking_mutex::Mutex in order to get direct mutable access to the protected data. This removes the need for an extra RefCell when mutable access is needed.

The method is marked unsafe because calling this method when the mutex is already locked causes UB. Other than that this implementation should be sound.

[lulf]

My only reservation here is that having this API we could be promoting a bad pattern of using lock_mut instead of the safer RefCell wrap, even if it's marked unsafe. At a minimum it should perhaps recommend using a RefCell in the docs to point the users towards that.

[avsaase]

I'll update the doc comment to point to the safer pattern of using a RefCell. But is it really a bad pattern? This is only marked unsafe because re-entrantly locking the mutex causes UB. I can't think of another way to misuse this.

You'd need to do something like this to shoot yourself in the foot:

unsafe {
    MUTEX.lock_mut(|value| {
        MUTEX.lock_mut(|value| /* 💥 */)
    })
}	

For a blocking mutex that can't be locked across await points it seems very unlikely that someone will overlook this.

That said, I also don't like the unsafety of this. I mostly added this to avoid the boilerplate of using a RefCell in a Mutex, but that could also be solved by writing a MutexCell or something like that.

[lulf]

Thanks!