Clean up docs formatting for Wasm runtime (#7869)

* Clean up docs formatting for Wasm runtime

* Update runtime.rs
This commit is contained in:
Alexey 2018-02-12 19:59:41 +03:00 committed by Afri Schoedon
parent fab03398dd
commit a30de1b8d8

View File

@ -137,7 +137,9 @@ impl<'a> Runtime<'a> {
Ok(U256::from_big_endian(&buf[..])) Ok(U256::from_big_endian(&buf[..]))
} }
/// Charge specified amount of gas, returning false is gas limit exceeded, true if not. /// Charge specified amount of gas
///
/// Returns false if gas limit exceeded and true if not.
/// Intuition about the return value sense is to aswer the question 'are we allowed to continue?' /// Intuition about the return value sense is to aswer the question 'are we allowed to continue?'
fn charge_gas(&mut self, amount: u64) -> bool { fn charge_gas(&mut self, amount: u64) -> bool {
let prev = self.gas_counter; let prev = self.gas_counter;
@ -169,8 +171,9 @@ impl<'a> Runtime<'a> {
self.charge(|schedule| f(schedule) * schedule.wasm.opcodes_div as u64 / schedule.wasm.opcodes_mul as u64) self.charge(|schedule| f(schedule) * schedule.wasm.opcodes_div as u64 / schedule.wasm.opcodes_mul as u64)
} }
/// Charge gas provided by the closure, and closure also can return overflowing /// Charge gas provided by the closure
/// flag as None in gas cost. ///
/// Closure also can return overflowing flag as None in gas cost.
pub fn overflow_charge<F>(&mut self, f: F) -> Result<()> pub fn overflow_charge<F>(&mut self, f: F) -> Result<()>
where F: FnOnce(&vm::Schedule) -> Option<u64> where F: FnOnce(&vm::Schedule) -> Option<u64>
{ {
@ -197,7 +200,7 @@ impl<'a> Runtime<'a> {
) )
} }
/// Read from the storage to wasm memory. /// Read from the storage to wasm memory
pub fn storage_read(&mut self, args: RuntimeArgs) -> Result<()> pub fn storage_read(&mut self, args: RuntimeArgs) -> Result<()>
{ {
let key = self.h256_at(args.nth(0)?)?; let key = self.h256_at(args.nth(0)?)?;
@ -212,7 +215,7 @@ impl<'a> Runtime<'a> {
Ok(()) Ok(())
} }
/// Write to storage from wasm memory. /// Write to storage from wasm memory
pub fn storage_write(&mut self, args: RuntimeArgs) -> Result<()> pub fn storage_write(&mut self, args: RuntimeArgs) -> Result<()>
{ {
let key = self.h256_at(args.nth(0)?)?; let key = self.h256_at(args.nth(0)?)?;
@ -236,13 +239,16 @@ impl<'a> Runtime<'a> {
Ok(()) Ok(())
} }
/// Return currently used schedule. /// Return currently used schedule
pub fn schedule(&self) -> &vm::Schedule { pub fn schedule(&self) -> &vm::Schedule {
self.ext.schedule() self.ext.schedule()
} }
/// Return. Syscall takes 2 arguments - pointer in sandboxed memory where result is and /// Sets a return value for the call
/// the length of the result. ///
/// Syscall takes 2 arguments:
/// * pointer in sandboxed memory where result is
/// * the length of the result
pub fn ret(&mut self, args: RuntimeArgs) -> Result<()> { pub fn ret(&mut self, args: RuntimeArgs) -> Result<()> {
let ptr: u32 = args.nth(0)?; let ptr: u32 = args.nth(0)?;
let len: u32 = args.nth(1)?; let len: u32 = args.nth(1)?;
@ -254,7 +260,7 @@ impl<'a> Runtime<'a> {
Ok(()) Ok(())
} }
/// Destroy the runtime, returning currently recorded result of the execution. /// Destroy the runtime, returning currently recorded result of the execution
pub fn into_result(self) -> Vec<u8> { pub fn into_result(self) -> Vec<u8> {
self.result self.result
} }
@ -287,7 +293,9 @@ impl<'a> Runtime<'a> {
Ok(()) Ok(())
} }
/// User panic. Contract can invoke this when he encounters unrecoverable error. /// User panic
///
/// Contract can invoke this when he encounters unrecoverable error.
fn panic(&mut self, args: RuntimeArgs) -> Result<()> fn panic(&mut self, args: RuntimeArgs) -> Result<()>
{ {
let payload_ptr: u32 = args.nth(0)?; let payload_ptr: u32 = args.nth(0)?;
@ -413,17 +421,17 @@ impl<'a> Runtime<'a> {
} }
} }
/// Message call. /// Message call
fn ccall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> { fn ccall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> {
self.do_call(true, CallType::Call, args) self.do_call(true, CallType::Call, args)
} }
/// Delegate call. /// Delegate call
fn dcall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> { fn dcall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> {
self.do_call(false, CallType::DelegateCall, args) self.do_call(false, CallType::DelegateCall, args)
} }
/// STatic call. /// Static call
fn scall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> { fn scall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> {
self.do_call(false, CallType::StaticCall, args) self.do_call(false, CallType::StaticCall, args)
} }
@ -442,11 +450,19 @@ impl<'a> Runtime<'a> {
Ok(()) Ok(())
} }
/// Returns value (in Wei) passed to contract
pub fn value(&mut self, args: RuntimeArgs) -> Result<()> { pub fn value(&mut self, args: RuntimeArgs) -> Result<()> {
let val = self.context.value; let val = self.context.value;
self.return_u256_ptr(args.nth(0)?, val) self.return_u256_ptr(args.nth(0)?, val)
} }
/// Creates a new contract
///
/// Arguments:
/// * endowment - how much value (in Wei) transfer to the newly created contract
/// * code_ptr - pointer to the code data
/// * code_len - lenght of the code data
/// * result_ptr - pointer to write an address of the newly created contract
pub fn create(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> pub fn create(&mut self, args: RuntimeArgs) -> Result<RuntimeValue>
{ {
// //
@ -532,6 +548,7 @@ impl<'a> Runtime<'a> {
Err(Error::Suicide.into()) Err(Error::Suicide.into())
} }
/// Signature: `fn blockhash(number: i64, dest: *mut u8)`
pub fn blockhash(&mut self, args: RuntimeArgs) -> Result<()> { pub fn blockhash(&mut self, args: RuntimeArgs) -> Result<()> {
self.adjusted_charge(|schedule| schedule.blockhash_gas as u64)?; self.adjusted_charge(|schedule| schedule.blockhash_gas as u64)?;
let hash = self.ext.blockhash(&U256::from(args.nth::<u64>(0)?)); let hash = self.ext.blockhash(&U256::from(args.nth::<u64>(0)?));
@ -540,49 +557,56 @@ impl<'a> Runtime<'a> {
Ok(()) Ok(())
} }
/// Signature: `fn blocknumber() -> i64`
pub fn blocknumber(&mut self) -> Result<RuntimeValue> { pub fn blocknumber(&mut self) -> Result<RuntimeValue> {
Ok(RuntimeValue::from(self.ext.env_info().number)) Ok(RuntimeValue::from(self.ext.env_info().number))
} }
/// Signature: `fn coinbase(dest: *mut u8)`
pub fn coinbase(&mut self, args: RuntimeArgs) -> Result<()> { pub fn coinbase(&mut self, args: RuntimeArgs) -> Result<()> {
let coinbase = self.ext.env_info().author; let coinbase = self.ext.env_info().author;
self.return_address_ptr(args.nth(0)?, coinbase) self.return_address_ptr(args.nth(0)?, coinbase)
} }
/// Signature: `fn difficulty(dest: *mut u8)`
pub fn difficulty(&mut self, args: RuntimeArgs) -> Result<()> { pub fn difficulty(&mut self, args: RuntimeArgs) -> Result<()> {
let difficulty = self.ext.env_info().difficulty; let difficulty = self.ext.env_info().difficulty;
self.return_u256_ptr(args.nth(0)?, difficulty) self.return_u256_ptr(args.nth(0)?, difficulty)
} }
/// Signature: `fn gaslimit(dest: *mut u8)`
pub fn gaslimit(&mut self, args: RuntimeArgs) -> Result<()> { pub fn gaslimit(&mut self, args: RuntimeArgs) -> Result<()> {
let gas_limit = self.ext.env_info().gas_limit; let gas_limit = self.ext.env_info().gas_limit;
self.return_u256_ptr(args.nth(0)?, gas_limit) self.return_u256_ptr(args.nth(0)?, gas_limit)
} }
/// Signature: `fn address(dest: *mut u8)`
pub fn address(&mut self, args: RuntimeArgs) -> Result<()> { pub fn address(&mut self, args: RuntimeArgs) -> Result<()> {
let address = self.context.address; let address = self.context.address;
self.return_address_ptr(args.nth(0)?, address) self.return_address_ptr(args.nth(0)?, address)
} }
/// Signature: `sender(dest: *mut u8)`
pub fn sender(&mut self, args: RuntimeArgs) -> Result<()> { pub fn sender(&mut self, args: RuntimeArgs) -> Result<()> {
let sender = self.context.sender; let sender = self.context.sender;
self.return_address_ptr(args.nth(0)?, sender) self.return_address_ptr(args.nth(0)?, sender)
} }
/// Signature: `origin(dest: *mut u8)`
pub fn origin(&mut self, args: RuntimeArgs) -> Result<()> { pub fn origin(&mut self, args: RuntimeArgs) -> Result<()> {
let origin = self.context.origin; let origin = self.context.origin;
self.return_address_ptr(args.nth(0)?, origin) self.return_address_ptr(args.nth(0)?, origin)
} }
/// Signature: `timestamp() -> i64`
pub fn timestamp(&mut self) -> Result<RuntimeValue> { pub fn timestamp(&mut self) -> Result<RuntimeValue> {
let timestamp = self.ext.env_info().timestamp; let timestamp = self.ext.env_info().timestamp;
Ok(RuntimeValue::from(timestamp)) Ok(RuntimeValue::from(timestamp))
} }
/// Signature: `fn elog(topic_ptr: *const u8, topic_count: u32, data_ptr: *const u8, data_len: u32)`
pub fn elog(&mut self, args: RuntimeArgs) -> Result<()> pub fn elog(&mut self, args: RuntimeArgs) -> Result<()>
{ {
// signature is:
// pub fn elog(topic_ptr: *const u8, topic_count: u32, data_ptr: *const u8, data_len: u32);
let topic_ptr: u32 = args.nth(0)?; let topic_ptr: u32 = args.nth(0)?;
let topic_count: u32 = args.nth(1)?; let topic_count: u32 = args.nth(1)?;
let data_ptr: u32 = args.nth(2)?; let data_ptr: u32 = args.nth(2)?;