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[..]))
}
/// 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?'
fn charge_gas(&mut self, amount: u64) -> bool {
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)
}
/// Charge gas provided by the closure, and closure also can return overflowing
/// flag as None in gas cost.
/// Charge gas provided by the closure
///
/// Closure also can return overflowing flag as None in gas cost.
pub fn overflow_charge<F>(&mut self, f: F) -> Result<()>
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<()>
{
let key = self.h256_at(args.nth(0)?)?;
@ -212,7 +215,7 @@ impl<'a> Runtime<'a> {
Ok(())
}
/// Write to storage from wasm memory.
/// Write to storage from wasm memory
pub fn storage_write(&mut self, args: RuntimeArgs) -> Result<()>
{
let key = self.h256_at(args.nth(0)?)?;
@ -236,13 +239,16 @@ impl<'a> Runtime<'a> {
Ok(())
}
/// Return currently used schedule.
/// Return currently used schedule
pub fn schedule(&self) -> &vm::Schedule {
self.ext.schedule()
}
/// Return. Syscall takes 2 arguments - pointer in sandboxed memory where result is and
/// the length of the result.
/// Sets a return value for the call
///
/// Syscall takes 2 arguments:
/// * pointer in sandboxed memory where result is
/// * the length of the result
pub fn ret(&mut self, args: RuntimeArgs) -> Result<()> {
let ptr: u32 = args.nth(0)?;
let len: u32 = args.nth(1)?;
@ -254,7 +260,7 @@ impl<'a> Runtime<'a> {
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> {
self.result
}
@ -287,7 +293,9 @@ impl<'a> Runtime<'a> {
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<()>
{
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> {
self.do_call(true, CallType::Call, args)
}
/// Delegate call.
/// Delegate call
fn dcall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> {
self.do_call(false, CallType::DelegateCall, args)
}
/// STatic call.
/// Static call
fn scall(&mut self, args: RuntimeArgs) -> Result<RuntimeValue> {
self.do_call(false, CallType::StaticCall, args)
}
@ -442,11 +450,19 @@ impl<'a> Runtime<'a> {
Ok(())
}
/// Returns value (in Wei) passed to contract
pub fn value(&mut self, args: RuntimeArgs) -> Result<()> {
let val = self.context.value;
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>
{
//
@ -532,6 +548,7 @@ impl<'a> Runtime<'a> {
Err(Error::Suicide.into())
}
/// Signature: `fn blockhash(number: i64, dest: *mut u8)`
pub fn blockhash(&mut self, args: RuntimeArgs) -> Result<()> {
self.adjusted_charge(|schedule| schedule.blockhash_gas as u64)?;
let hash = self.ext.blockhash(&U256::from(args.nth::<u64>(0)?));
@ -540,49 +557,56 @@ impl<'a> Runtime<'a> {
Ok(())
}
/// Signature: `fn blocknumber() -> i64`
pub fn blocknumber(&mut self) -> Result<RuntimeValue> {
Ok(RuntimeValue::from(self.ext.env_info().number))
}
/// Signature: `fn coinbase(dest: *mut u8)`
pub fn coinbase(&mut self, args: RuntimeArgs) -> Result<()> {
let coinbase = self.ext.env_info().author;
self.return_address_ptr(args.nth(0)?, coinbase)
}
/// Signature: `fn difficulty(dest: *mut u8)`
pub fn difficulty(&mut self, args: RuntimeArgs) -> Result<()> {
let difficulty = self.ext.env_info().difficulty;
self.return_u256_ptr(args.nth(0)?, difficulty)
}
/// Signature: `fn gaslimit(dest: *mut u8)`
pub fn gaslimit(&mut self, args: RuntimeArgs) -> Result<()> {
let gas_limit = self.ext.env_info().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<()> {
let address = self.context.address;
self.return_address_ptr(args.nth(0)?, address)
}
/// Signature: `sender(dest: *mut u8)`
pub fn sender(&mut self, args: RuntimeArgs) -> Result<()> {
let sender = self.context.sender;
self.return_address_ptr(args.nth(0)?, sender)
}
/// Signature: `origin(dest: *mut u8)`
pub fn origin(&mut self, args: RuntimeArgs) -> Result<()> {
let origin = self.context.origin;
self.return_address_ptr(args.nth(0)?, origin)
}
/// Signature: `timestamp() -> i64`
pub fn timestamp(&mut self) -> Result<RuntimeValue> {
let timestamp = self.ext.env_info().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<()>
{
// 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_count: u32 = args.nth(1)?;
let data_ptr: u32 = args.nth(2)?;