offchain storage lock

[drahnr]

A storage locking API for use within the storage API.

Importance here has correctness above everything else.

Fixes #6004

[tomusdrw]

A great deal of typos and I feel the API of the lock does not fit into our OCW use cases that much. Having the block-based lock (instead of time-based) would immediately be applicable for offchain phragmen and im-online pallets. I guess if we really want we can implement something that cover both cases, but for now I think the block-based one is more important.

[tomusdrw]

Spoke with @drahnr off github and he gave me a bit more context on the motivations here. Brief summary:

1. Block-based locks are not reliable if we assume multiple OCWs for different blocks can run concurrently. Imagine two workers OCW(N) and OCW(N+X) running at the same time, OCW(N) acquires a lock, but OCW(N+X) may consider it stale right away if the lock is acquired for less than X blocks. Timestamp based locks are more reliable in that regard.

2. Bernhard proposed a more generic approach to locking, where the StorageLock logic is separated from Lockable, which might be Time or BlockAndTime. In the latter case both conditions have to be satisfied (say we lock for both: at least 4 blocks and 1 second).

3. The StorageLock API will probably be simplfiied to:

• try_lock - acquire or fail
• spin_lock - block trying to acquire lock, but with a safety limit (similar to how HTTP wait has a host timeout)
  Other cases (lock forever, lock with deadline) can be easily implemented using try_lock, but since we don't see use cases for now we don't want to endorse that usage.

[drahnr]

There still needs to be done some shifting around, the impl is not quite complete yet.

[drahnr]

3. The `StorageLock` API will probably be simplfiied to:


* `try_lock` - acquire or fail

* `spin_lock` - block trying to acquire lock, but with a safety limit (similar to how HTTP wait has a host timeout)
  Other cases (lock forever, lock with deadline) can be easily implemented using `try_lock`, but since we don't see use cases for now we don't want to endorse that usage.

Minor correction: #3 can be implemented in unsafe code OR if using private fn try_lock_inner - this is due to lifetimes of the borrow of self and the StorageLockGuard combined with the loop in which you would need to call try_lock which will try to borrow for the same lifetime as StorageLockGuard which is impossible for rustc to derive when done withing a loop with return.

---

To be a little more explicit on the safety / host timeout-like mechanism:

Every lock will have an internal deadline (based on the type of impl Lockable) which determines if the locking state of a lock has gone stale. This guarantees implicitly that fn spin_lock() will succeed eventually as well as on unexpected termination the lock will not persist and block ocw execution indefinitely.

[tomusdrw]

Looks perfect, there are small suggestions here and there, but I think it's ready to merge.

[tomusdrw]

Docs 😍

[bkchr]

Private items are not shown in the docs by default