Trait gear_core::env::Externalities

source ·
pub trait Externalities {
    type UnrecoverableError;
    type FallibleError;
    type AllocError: Display;

Show 44 methods // Required methods fn alloc<Context>( &mut self, ctx: &mut Context, mem: &mut impl Memory<Context>, pages_num: u32, ) -> Result<WasmPage, Self::AllocError>; fn free(&mut self, page: WasmPage) -> Result<(), Self::AllocError>; fn free_range( &mut self, start: WasmPage, end: WasmPage, ) -> Result<(), Self::AllocError>; fn env_vars( &self, version: u32, ) -> Result<EnvVars, Self::UnrecoverableError>; fn block_height(&self) -> Result<u32, Self::UnrecoverableError>; fn block_timestamp(&self) -> Result<u64, Self::UnrecoverableError>; fn send_init(&mut self) -> Result<u32, Self::FallibleError>; fn send_push( &mut self, handle: u32, buffer: &[u8], ) -> Result<(), Self::FallibleError>; fn send_commit( &mut self, handle: u32, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>; fn send_push_input( &mut self, handle: u32, offset: u32, len: u32, ) -> Result<(), Self::FallibleError>; fn reservation_send_commit( &mut self, id: ReservationId, handle: u32, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>; fn reply_push(&mut self, buffer: &[u8]) -> Result<(), Self::FallibleError>; fn reply_commit( &mut self, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>; fn reservation_reply_commit( &mut self, id: ReservationId, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>; fn reply_to(&self) -> Result<MessageId, Self::FallibleError>; fn signal_from(&self) -> Result<MessageId, Self::FallibleError>; fn reply_push_input( &mut self, offset: u32, len: u32, ) -> Result<(), Self::FallibleError>; fn source(&self) -> Result<ProgramId, Self::UnrecoverableError>; fn reply_code(&self) -> Result<ReplyCode, Self::FallibleError>; fn signal_code(&self) -> Result<SignalCode, Self::FallibleError>; fn message_id(&self) -> Result<MessageId, Self::UnrecoverableError>; fn program_id(&self) -> Result<ProgramId, Self::UnrecoverableError>; fn debug(&self, data: &str) -> Result<(), Self::UnrecoverableError>; fn lock_payload( &mut self, at: u32, len: u32, ) -> Result<PayloadSliceLock, Self::FallibleError>; fn unlock_payload( &mut self, payload_holder: &mut PayloadSliceLock, ) -> UnlockPayloadBound; fn size(&self) -> Result<usize, Self::UnrecoverableError>; fn random(&self) -> Result<(&[u8], u32), Self::UnrecoverableError>; fn reserve_gas( &mut self, amount: u64, duration: u32, ) -> Result<ReservationId, Self::FallibleError>; fn unreserve_gas( &mut self, id: ReservationId, ) -> Result<u64, Self::FallibleError>; fn system_reserve_gas( &mut self, amount: u64, ) -> Result<(), Self::FallibleError>; fn gas_available(&self) -> Result<u64, Self::UnrecoverableError>; fn value(&self) -> Result<u128, Self::UnrecoverableError>; fn value_available(&self) -> Result<u128, Self::UnrecoverableError>; fn wait(&mut self) -> Result<(), Self::UnrecoverableError>; fn wait_for( &mut self, duration: u32, ) -> Result<(), Self::UnrecoverableError>; fn wait_up_to( &mut self, duration: u32, ) -> Result<bool, Self::UnrecoverableError>; fn wake( &mut self, waker_id: MessageId, delay: u32, ) -> Result<(), Self::FallibleError>; fn create_program( &mut self, packet: InitPacket, delay: u32, ) -> Result<(MessageId, ProgramId), Self::FallibleError>; fn reply_deposit( &mut self, message_id: MessageId, amount: u64, ) -> Result<(), Self::FallibleError>; fn forbidden_funcs(&self) -> &BTreeSet<SyscallName>; // Provided methods fn send( &mut self, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError> { ... } fn reservation_send( &mut self, id: ReservationId, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError> { ... } fn reply( &mut self, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError> { ... } fn reservation_reply( &mut self, id: ReservationId, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError> { ... }
}
Expand description

External api and data for managing memory and messages, use by an executing program to trigger state transition in runtime.

Required Associated Types§

source

type UnrecoverableError

An error issued in infallible syscall.

source

type FallibleError

An error issued in fallible syscall.

source

type AllocError: Display

An error issued during allocation.

Required Methods§

source

fn alloc<Context>( &mut self, ctx: &mut Context, mem: &mut impl Memory<Context>, pages_num: u32, ) -> Result<WasmPage, Self::AllocError>

Allocate number of pages.

The resulting page number should point to pages consecutive memory pages.

source

fn free(&mut self, page: WasmPage) -> Result<(), Self::AllocError>

Free specific page.

source

fn free_range( &mut self, start: WasmPage, end: WasmPage, ) -> Result<(), Self::AllocError>

Free specific memory range.

source

fn env_vars(&self, version: u32) -> Result<EnvVars, Self::UnrecoverableError>

Get environment variables currently set in the system and in the form corresponded to the requested version.

source

fn block_height(&self) -> Result<u32, Self::UnrecoverableError>

Get the current block height.

source

fn block_timestamp(&self) -> Result<u64, Self::UnrecoverableError>

Get the current block timestamp.

source

fn send_init(&mut self) -> Result<u32, Self::FallibleError>

Initialize a new incomplete message for another program and return its handle.

source

fn send_push( &mut self, handle: u32, buffer: &[u8], ) -> Result<(), Self::FallibleError>

Push an extra buffer into message payload by handle.

source

fn send_commit( &mut self, handle: u32, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Complete message and send it to another program.

source

fn send_push_input( &mut self, handle: u32, offset: u32, len: u32, ) -> Result<(), Self::FallibleError>

Push the incoming message buffer into message payload by handle.

source

fn reservation_send_commit( &mut self, id: ReservationId, handle: u32, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Complete message and send it to another program using gas from reservation.

source

fn reply_push(&mut self, buffer: &[u8]) -> Result<(), Self::FallibleError>

Push an extra buffer into reply message.

source

fn reply_commit( &mut self, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>

Complete reply message and send it to source program.

source

fn reservation_reply_commit( &mut self, id: ReservationId, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>

Complete reply message and send it to source program from reservation.

source

fn reply_to(&self) -> Result<MessageId, Self::FallibleError>

Get the message id of the initial message.

source

fn signal_from(&self) -> Result<MessageId, Self::FallibleError>

Get the message id which signal issues from.

source

fn reply_push_input( &mut self, offset: u32, len: u32, ) -> Result<(), Self::FallibleError>

Push the incoming message buffer into reply message.

source

fn source(&self) -> Result<ProgramId, Self::UnrecoverableError>

Get the source of the message currently being handled.

source

fn reply_code(&self) -> Result<ReplyCode, Self::FallibleError>

Get the reply code if the message being processed.

source

fn signal_code(&self) -> Result<SignalCode, Self::FallibleError>

Get the signal code if the message being processed.

source

fn message_id(&self) -> Result<MessageId, Self::UnrecoverableError>

Get the id of the message currently being handled.

source

fn program_id(&self) -> Result<ProgramId, Self::UnrecoverableError>

Get the id of program itself

source

fn debug(&self, data: &str) -> Result<(), Self::UnrecoverableError>

Send debug message.

This should be no-op in release builds.

source

fn lock_payload( &mut self, at: u32, len: u32, ) -> Result<PayloadSliceLock, Self::FallibleError>

Takes ownership over payload of the executing message and returns it in the wrapper PayloadSliceLock, which acts like lock.

Due to details of implementation of the runtime which executes gear syscalls inside wasm execution environment, to prevent additional memory allocation on payload read op, we give ownership over payload to the caller. Giving ownership over payload actually means, that the payload value in the currently executed message will become empty. To prevent from the risk of payload being not “returned” back to the message a Externalities::unlock_payload is introduced. For more info, read docs to PayloadSliceLock, DropPayloadLockBound, UnlockPayloadBound, PayloadSliceAccess types and their methods.

source

fn unlock_payload( &mut self, payload_holder: &mut PayloadSliceLock, ) -> UnlockPayloadBound

Reclaims ownership from the payload lock over previously taken payload from the currently executing message..

It’s supposed, that the implementation of the method calls PayloadSliceLock::release.

source

fn size(&self) -> Result<usize, Self::UnrecoverableError>

Size of currently handled message payload.

source

fn random(&self) -> Result<(&[u8], u32), Self::UnrecoverableError>

Returns a random seed for the current block with message id as a subject, along with the time in the past since when it was determinable by chain observers.

source

fn reserve_gas( &mut self, amount: u64, duration: u32, ) -> Result<ReservationId, Self::FallibleError>

Reserve some gas for a few blocks.

source

fn unreserve_gas( &mut self, id: ReservationId, ) -> Result<u64, Self::FallibleError>

Unreserve gas using reservation ID.

source

fn system_reserve_gas(&mut self, amount: u64) -> Result<(), Self::FallibleError>

Do system reservation.

source

fn gas_available(&self) -> Result<u64, Self::UnrecoverableError>

Tell how much gas is left in running context.

source

fn value(&self) -> Result<u128, Self::UnrecoverableError>

Value associated with message.

source

fn value_available(&self) -> Result<u128, Self::UnrecoverableError>

Tell how much value is left in running context.

source

fn wait(&mut self) -> Result<(), Self::UnrecoverableError>

Interrupt the program and reschedule execution for maximum.

source

fn wait_for(&mut self, duration: u32) -> Result<(), Self::UnrecoverableError>

Interrupt the program and reschedule execution in duration.

source

fn wait_up_to( &mut self, duration: u32, ) -> Result<bool, Self::UnrecoverableError>

Interrupt the program and reschedule execution for maximum, but not more than duration.

source

fn wake( &mut self, waker_id: MessageId, delay: u32, ) -> Result<(), Self::FallibleError>

Wake the waiting message and move it to the processing queue.

source

fn create_program( &mut self, packet: InitPacket, delay: u32, ) -> Result<(MessageId, ProgramId), Self::FallibleError>

Send init message to create a new program.

source

fn reply_deposit( &mut self, message_id: MessageId, amount: u64, ) -> Result<(), Self::FallibleError>

Create deposit to handle reply on given message.

source

fn forbidden_funcs(&self) -> &BTreeSet<SyscallName>

Return the set of functions that are forbidden to be called.

Provided Methods§

source

fn send( &mut self, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Send message to another program.

source

fn reservation_send( &mut self, id: ReservationId, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Send message to another program using gas from reservation.

source

fn reply(&mut self, msg: ReplyPacket) -> Result<MessageId, Self::FallibleError>

Produce reply to the current message.

source

fn reservation_reply( &mut self, id: ReservationId, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>

Produce reply to the current message from reservation.

Object Safety§

This trait is not object safe.

Implementors§