sync: add Receiver::borrow_and_update

[Darksonn]

Add a method similar to borrow that updates the version counter. Using this method, it would be possible to update WatchStream to avoid the issue described by #3655.

Fixes: #3666
Closes: #3731

[carllerche]

My guess is you considered updating the borrow() fn to this behavior before adding a new fn and noticed that the version field in Receiver couldn't be updated with &self? Looking at the code, I would probably change Receiver::version to an AtomicUsize. It should be safe to load / store w/ SeqCst while the read lock is held. Shared::version can only be updated when the write lock is held, so any concurrent calls to Receiver::borrow will observe the same value.

[carllerche]

Looking more at this, I don't see any obvious reason for Shared::version to be atomic instead of just being guarded by the RwLock. Switching to that would probably simplify the code.

[Darksonn]

My guess is you considered updating the borrow() fn to this behavior before adding a new fn and noticed that the version field in Receiver couldn't be updated with &self?

No, that isn't the reason. It seems to me that changing the behavior of borrow() in this manner should constitute a breaking change.

[Darksonn]

Looking more at this, I don't see any obvious reason for Shared::version to be atomic instead of just being guarded by the RwLock. Switching to that would probably simplify the code.

As it is now, the changed method doesn't take any locks, which would have to change if we make it non-atomic. That said, we might be able to relax the ordering.

Besides that, there's also the closed flag which is stored as the least-significant bit in the version counter.

[carllerche]

Hmmm, yes, technically it could be a breaking change as we documented changed() as notifying if there were any changes since last call to changed(). I think it is debatable whether it is really a breaking change, but I'm ok w/ adding a new fn.

We probably should be sure to document the differences between the two borrow_* fns (each fn can include a bit saying how it is different from the other).

We probably should tweak the changed() doc as it won't raise a notification if a change occurred since the last call to changed() if borrow_and_update was called.

[carllerche]

Looking more at this, I don't see any obvious reason for Shared::version to be atomic instead of just being guarded by the RwLock. Switching to that would probably simplify the code.

As it is now, the changed method doesn't take any locks, which would have to change if we make it non-atomic. That said, we might be able to relax the ordering.

Besides that, there's also the closed flag which is stored as the least-significant bit in the version counter.

True... though fetch_add could be changed to load / store i think... anyway, it isn't related to this PR, so no need to make that change.

[Darksonn]

What do you think of the name of the function?

[carllerche]

It seems fine!

[carllerche]

Thanks 👍