Struct gear_core::env::PayloadSliceLock

pub struct PayloadSliceLock { /* private fields */ }

Lock for the payload of the incoming/currently executing message.

The type was mainly introduced to establish type safety mechanics for the read of the payload from externalities. To type’s purposes see Externalities::lock_payload docs.

Usage

This type gives access to some slice of the currently executing message payload, but doesn’t do it directly. It gives to the caller the PayloadSliceAccess wrapper, which actually can return the slice of the payload. But this wrapper is instantiated only inside the Self::drop_with method. This is actually done to prevent a user of the type from locking payload of the message, which actually moves it, and forgetting to unlock it back, because if access to the slice buffer was granted directly from the holder, the type user could have written the data to memory and then have dropped the holder. As a result the executing message payload wouldn’t have been returned. So PayloadSliceLock::drop_with is a kind of scope-guard for the data and the PayloadSliceAccess is a data access guard.

For more usage info read Self::drop_with docs.

Implementations

impl PayloadSliceLock

pub fn try_new( (start, end): (u32, u32), msg_ctx: &mut MessageContext, ) -> Option<Self>

Creates a new PayloadSliceLock from the currently executed message context.

The method checks whether received range (slice) is correct, i.e., the end is lower than payload’s length. If the check goes well, the ownership over payload will be taken from the message context by mem::take.

pub fn drop_with<JobErr, Job>(self, job: Job) -> DropPayloadLockBound<JobErr>

where Job: FnMut(PayloadSliceAccess<'_>) -> DropPayloadLockBound<JobErr>,

Uses the lock in the provided job and drops the lock after running it.

PayloadSliceLock’s main purpose is to provide safe access to the payload’s slice and ensure it will be returned back to the message.

Type docs explain how safe access is designed with PayloadSliceAccess.

We ensure that the payload is released back by returning the DropPayloadLockBound from the job. This type can actually be instantiated only from tuple of two: UnlockPayloadBound and some result with err variant type to be JobErr. The first is returned from Externalities::unlock_payload, so it means that that payload was reclaimed by the original owner. The other result stores actual error of the Job as it could have called fallible actions inside it. So, DropPayloadLockBound gives an opportunity to store the actual result of the job, but also gives guarantee that payload was reclaimed.