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§
sourcetype UnrecoverableError
type UnrecoverableError
An error issued in infallible syscall.
sourcetype FallibleError
type FallibleError
An error issued in fallible syscall.
sourcetype AllocError: Display
type AllocError: Display
An error issued during allocation.
Required Methods§
sourcefn alloc<Context>(
&mut self,
ctx: &mut Context,
mem: &mut impl Memory<Context>,
pages_num: u32,
) -> Result<WasmPage, Self::AllocError>
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.
sourcefn free_range(
&mut self,
start: WasmPage,
end: WasmPage,
) -> Result<(), Self::AllocError>
fn free_range( &mut self, start: WasmPage, end: WasmPage, ) -> Result<(), Self::AllocError>
Free specific memory range.
sourcefn env_vars(&self, version: u32) -> Result<EnvVars, Self::UnrecoverableError>
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.
sourcefn block_height(&self) -> Result<u32, Self::UnrecoverableError>
fn block_height(&self) -> Result<u32, Self::UnrecoverableError>
Get the current block height.
sourcefn block_timestamp(&self) -> Result<u64, Self::UnrecoverableError>
fn block_timestamp(&self) -> Result<u64, Self::UnrecoverableError>
Get the current block timestamp.
sourcefn send_init(&mut self) -> Result<u32, Self::FallibleError>
fn send_init(&mut self) -> Result<u32, Self::FallibleError>
Initialize a new incomplete message for another program and return its handle.
sourcefn send_push(
&mut self,
handle: u32,
buffer: &[u8],
) -> Result<(), Self::FallibleError>
fn send_push( &mut self, handle: u32, buffer: &[u8], ) -> Result<(), Self::FallibleError>
Push an extra buffer into message payload by handle.
sourcefn send_commit(
&mut self,
handle: u32,
msg: HandlePacket,
delay: u32,
) -> Result<MessageId, Self::FallibleError>
fn send_commit( &mut self, handle: u32, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>
Complete message and send it to another program.
sourcefn send_push_input(
&mut self,
handle: u32,
offset: u32,
len: u32,
) -> Result<(), Self::FallibleError>
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.
sourcefn reservation_send_commit(
&mut self,
id: ReservationId,
handle: u32,
msg: HandlePacket,
delay: u32,
) -> Result<MessageId, Self::FallibleError>
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.
sourcefn reply_push(&mut self, buffer: &[u8]) -> Result<(), Self::FallibleError>
fn reply_push(&mut self, buffer: &[u8]) -> Result<(), Self::FallibleError>
Push an extra buffer into reply message.
sourcefn reply_commit(
&mut self,
msg: ReplyPacket,
) -> Result<MessageId, Self::FallibleError>
fn reply_commit( &mut self, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>
Complete reply message and send it to source program.
sourcefn reservation_reply_commit(
&mut self,
id: ReservationId,
msg: ReplyPacket,
) -> Result<MessageId, Self::FallibleError>
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.
sourcefn reply_to(&self) -> Result<MessageId, Self::FallibleError>
fn reply_to(&self) -> Result<MessageId, Self::FallibleError>
Get the message id of the initial message.
sourcefn signal_from(&self) -> Result<MessageId, Self::FallibleError>
fn signal_from(&self) -> Result<MessageId, Self::FallibleError>
Get the message id which signal issues from.
sourcefn reply_push_input(
&mut self,
offset: u32,
len: u32,
) -> Result<(), Self::FallibleError>
fn reply_push_input( &mut self, offset: u32, len: u32, ) -> Result<(), Self::FallibleError>
Push the incoming message buffer into reply message.
sourcefn source(&self) -> Result<ProgramId, Self::UnrecoverableError>
fn source(&self) -> Result<ProgramId, Self::UnrecoverableError>
Get the source of the message currently being handled.
sourcefn reply_code(&self) -> Result<ReplyCode, Self::FallibleError>
fn reply_code(&self) -> Result<ReplyCode, Self::FallibleError>
Get the reply code if the message being processed.
sourcefn signal_code(&self) -> Result<SignalCode, Self::FallibleError>
fn signal_code(&self) -> Result<SignalCode, Self::FallibleError>
Get the signal code if the message being processed.
sourcefn message_id(&self) -> Result<MessageId, Self::UnrecoverableError>
fn message_id(&self) -> Result<MessageId, Self::UnrecoverableError>
Get the id of the message currently being handled.
sourcefn program_id(&self) -> Result<ProgramId, Self::UnrecoverableError>
fn program_id(&self) -> Result<ProgramId, Self::UnrecoverableError>
Get the id of program itself
sourcefn debug(&self, data: &str) -> Result<(), Self::UnrecoverableError>
fn debug(&self, data: &str) -> Result<(), Self::UnrecoverableError>
Send debug message.
This should be no-op in release builds.
sourcefn lock_payload(
&mut self,
at: u32,
len: u32,
) -> Result<PayloadSliceLock, Self::FallibleError>
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.
sourcefn unlock_payload(
&mut self,
payload_holder: &mut PayloadSliceLock,
) -> UnlockPayloadBound
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
.
sourcefn size(&self) -> Result<usize, Self::UnrecoverableError>
fn size(&self) -> Result<usize, Self::UnrecoverableError>
Size of currently handled message payload.
sourcefn random(&self) -> Result<(&[u8], u32), Self::UnrecoverableError>
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.
sourcefn reserve_gas(
&mut self,
amount: u64,
duration: u32,
) -> Result<ReservationId, Self::FallibleError>
fn reserve_gas( &mut self, amount: u64, duration: u32, ) -> Result<ReservationId, Self::FallibleError>
Reserve some gas for a few blocks.
sourcefn unreserve_gas(
&mut self,
id: ReservationId,
) -> Result<u64, Self::FallibleError>
fn unreserve_gas( &mut self, id: ReservationId, ) -> Result<u64, Self::FallibleError>
Unreserve gas using reservation ID.
sourcefn system_reserve_gas(&mut self, amount: u64) -> Result<(), Self::FallibleError>
fn system_reserve_gas(&mut self, amount: u64) -> Result<(), Self::FallibleError>
Do system reservation.
sourcefn gas_available(&self) -> Result<u64, Self::UnrecoverableError>
fn gas_available(&self) -> Result<u64, Self::UnrecoverableError>
Tell how much gas is left in running context.
sourcefn value(&self) -> Result<u128, Self::UnrecoverableError>
fn value(&self) -> Result<u128, Self::UnrecoverableError>
Value associated with message.
sourcefn value_available(&self) -> Result<u128, Self::UnrecoverableError>
fn value_available(&self) -> Result<u128, Self::UnrecoverableError>
Tell how much value is left in running context.
sourcefn wait(&mut self) -> Result<(), Self::UnrecoverableError>
fn wait(&mut self) -> Result<(), Self::UnrecoverableError>
Interrupt the program and reschedule execution for maximum.
sourcefn wait_for(&mut self, duration: u32) -> Result<(), Self::UnrecoverableError>
fn wait_for(&mut self, duration: u32) -> Result<(), Self::UnrecoverableError>
Interrupt the program and reschedule execution in duration.
sourcefn wait_up_to(
&mut self,
duration: u32,
) -> Result<bool, Self::UnrecoverableError>
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.
sourcefn wake(
&mut self,
waker_id: MessageId,
delay: u32,
) -> Result<(), Self::FallibleError>
fn wake( &mut self, waker_id: MessageId, delay: u32, ) -> Result<(), Self::FallibleError>
Wake the waiting message and move it to the processing queue.
sourcefn create_program(
&mut self,
packet: InitPacket,
delay: u32,
) -> Result<(MessageId, ProgramId), Self::FallibleError>
fn create_program( &mut self, packet: InitPacket, delay: u32, ) -> Result<(MessageId, ProgramId), Self::FallibleError>
Send init message to create a new program.
sourcefn reply_deposit(
&mut self,
message_id: MessageId,
amount: u64,
) -> Result<(), Self::FallibleError>
fn reply_deposit( &mut self, message_id: MessageId, amount: u64, ) -> Result<(), Self::FallibleError>
Create deposit to handle reply on given message.
sourcefn forbidden_funcs(&self) -> &BTreeSet<SyscallName>
fn forbidden_funcs(&self) -> &BTreeSet<SyscallName>
Return the set of functions that are forbidden to be called.
Provided Methods§
sourcefn send(
&mut self,
msg: HandlePacket,
delay: u32,
) -> Result<MessageId, Self::FallibleError>
fn send( &mut self, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>
Send message to another program.
sourcefn reservation_send(
&mut self,
id: ReservationId,
msg: HandlePacket,
delay: u32,
) -> Result<MessageId, Self::FallibleError>
fn reservation_send( &mut self, id: ReservationId, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>
Send message to another program using gas from reservation.
sourcefn reply(&mut self, msg: ReplyPacket) -> Result<MessageId, Self::FallibleError>
fn reply(&mut self, msg: ReplyPacket) -> Result<MessageId, Self::FallibleError>
Produce reply to the current message.
sourcefn reservation_reply(
&mut self,
id: ReservationId,
msg: ReplyPacket,
) -> Result<MessageId, Self::FallibleError>
fn reservation_reply( &mut self, id: ReservationId, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>
Produce reply to the current message from reservation.