grassrootseconomics/openethereum
5
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #292 from ethcore/util_docs

Browse Source 
Util docs
This commit is contained in:
Gav Wood 2016-02-01 16:21:45 +01:00
commit 4a25476161
13 changed files with 146 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
util/src/common.rs
View File

@ -1,3 +1,5 @@
//! Utils common types and macros global reexport.
pub use standard::*; pub use standard::*;
pub use from_json::*; pub use from_json::*;
pub use error::*; pub use error::*;

2
util/src/crypto.rs
View File

@ -1,3 +1,5 @@
//! Ethcore crypto.
use hash::*; use hash::*;
use bytes::*; use bytes::*;
use uint::*; use uint::*;

2
util/src/from_json.rs
View File

@ -1,3 +1,5 @@
//! Coversion from json.
use standard::*; use standard::*;
#[macro_export] #[macro_export]

2
util/src/heapsizeof.rs
View File

@ -1,3 +1,5 @@
//! Calculates heapsize of util types.
use uint::*; use uint::*;
use hash::*; use hash::*;

76
util/src/io/mod.rs
View File

@ -1,41 +1,41 @@
/// General IO module. //! General IO module.
/// //!
/// Example usage for craeting a network service and adding an IO handler: //! Example usage for creating a network service and adding an IO handler:
/// //!
/// ```rust //! ```rust
/// extern crate ethcore_util; //! extern crate ethcore_util;
/// use ethcore_util::*; //! use ethcore_util::*;
/// //!
/// struct MyHandler; //! struct MyHandler;
/// //!
/// #[derive(Clone)] //! #[derive(Clone)]
/// struct MyMessage { //! struct MyMessage {
/// data: u32 //! data: u32
/// } //! }
/// //!
/// impl IoHandler<MyMessage> for MyHandler { //! impl IoHandler<MyMessage> for MyHandler {
/// fn initialize(&self, io: &IoContext<MyMessage>) { //! fn initialize(&self, io: &IoContext<MyMessage>) {
/// io.register_timer(0, 1000).unwrap(); //! io.register_timer(0, 1000).unwrap();
/// } //! }
/// //!
/// fn timeout(&self, _io: &IoContext<MyMessage>, timer: TimerToken) { //! fn timeout(&self, _io: &IoContext<MyMessage>, timer: TimerToken) {
/// println!("Timeout {}", timer); //! println!("Timeout {}", timer);
/// } //! }
/// //!
/// fn message(&self, _io: &IoContext<MyMessage>, message: &MyMessage) { //! fn message(&self, _io: &IoContext<MyMessage>, message: &MyMessage) {
/// println!("Message {}", message.data); //! println!("Message {}", message.data);
/// } //! }
/// } //! }
/// //!
/// fn main () { //! fn main () {
/// let mut service = IoService::<MyMessage>::start().expect("Error creating network service"); //! let mut service = IoService::<MyMessage>::start().expect("Error creating network service");
/// service.register_handler(Arc::new(MyHandler)).unwrap(); //! service.register_handler(Arc::new(MyHandler)).unwrap();
/// //!
/// // Wait for quit condition //! // Wait for quit condition
/// // ... //! // ...
/// // Drop the service //! // Drop the service
/// } //! }
/// ``` //! ```
mod service; mod service;
mod worker; mod worker;

64
util/src/lib.rs
View File

@ -8,30 +8,55 @@
//! Ethcore-util library //! Ethcore-util library
//! //!
//! ### Rust version: //! ### Rust version:
//! - beta
//! - nightly //! - nightly
//! //!
//! ### Supported platforms: //! ### Supported platforms:
//! - OSX //! - OSX
//! - Linux //! - Linux
//! //!
//! ### Dependencies: //! ### Building:
//! - RocksDB 3.13
//! //!
//! ### Dependencies Installation: //! - Ubuntu 14.04 and later:
//!
//! ```bash
//! # install rocksdb
//! add-apt-repository "deb http://ppa.launchpad.net/giskou/librocksdb/ubuntu trusty main"
//! apt-get update
//! apt-get install -y --force-yes librocksdb
//!
//! # install multirust
//! curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sh -s -- --yes
//!
//! # install nightly and make it default
//! multirust update nightly && multirust default nightly
//!
//! # export rust LIBRARY_PATH
//! export LIBRARY_PATH=/usr/local/lib
//!
//! # download and build parity
//! git clone https://github.com/ethcore/parity
//! cd parity
//! cargo build --release
//! ```
//! //!
//! - OSX: //! - OSX:
//! //!
//! ```bash //! ```bash
//! # install rocksdb && multirust
//! brew update
//! brew install rocksdb //! brew install rocksdb
//! ``` //! brew install multirust
//! //!
//! - From source: //! # install nightly and make it default
//! multirust update nightly && multirust default nightly
//! //!
//! ```bash //! # export rust LIBRARY_PATH
//! wget https://github.com/facebook/rocksdb/archive/rocksdb-3.13.tar.gz //! export LIBRARY_PATH=/usr/local/lib
//! tar xvf rocksdb-3.13.tar.gz && cd rocksdb-rocksdb-3.13 && make shared_lib //!
//! sudo make install //! # download and build parity
//! git clone https://github.com/ethcore/parity
//! cd parity
//! cargo build --release
//! ``` //! ```
extern crate slab; extern crate slab;
@ -57,46 +82,34 @@ extern crate serde;
#[macro_use] #[macro_use]
extern crate log as rlog; extern crate log as rlog;
/// TODO [Gav Wood] Please document me
pub mod standard; pub mod standard;
#[macro_use] #[macro_use]
/// TODO [Gav Wood] Please document me
pub mod from_json; pub mod from_json;
#[macro_use] #[macro_use]
/// TODO [Gav Wood] Please document me
pub mod common; pub mod common;
pub mod error; pub mod error;
pub mod hash; pub mod hash;
pub mod uint; pub mod uint;
pub mod bytes; pub mod bytes;
pub mod rlp; pub mod rlp;
/// TODO [Gav Wood] Please document me
pub mod misc; pub mod misc;
/// TODO [Gav Wood] Please document me mod json_aid;
pub mod json_aid;
pub mod vector; pub mod vector;
pub mod sha3; pub mod sha3;
pub mod hashdb; pub mod hashdb;
pub mod memorydb; pub mod memorydb;
pub mod overlaydb; pub mod overlaydb;
pub mod journaldb; pub mod journaldb;
/// TODO [Gav Wood] Please document me mod math;
pub mod math;
pub mod chainfilter; pub mod chainfilter;
/// TODO [Gav Wood] Please document me
pub mod crypto; pub mod crypto;
pub mod triehash; pub mod triehash;
/// TODO [Gav Wood] Please document me
pub mod trie; pub mod trie;
pub mod nibbleslice; pub mod nibbleslice;
/// TODO [Gav Wood] Please document me mod heapsizeof;
pub mod heapsizeof;
pub mod squeeze; pub mod squeeze;
/// TODO [Gav Wood] Please document me
pub mod semantic_version; pub mod semantic_version;
/// TODO [Gav Wood] Please document me
pub mod io; pub mod io;
/// TODO [Gav Wood] Please document me
pub mod network; pub mod network;
pub mod log; pub mod log;
@ -114,7 +127,6 @@ pub use crypto::*;
pub use triehash::*; pub use triehash::*;
pub use trie::*; pub use trie::*;
pub use nibbleslice::*; pub use nibbleslice::*;
pub use heapsizeof::*;
pub use squeeze::*; pub use squeeze::*;
pub use semantic_version::*; pub use semantic_version::*;
pub use network::*; pub use network::*;

4
util/src/math.rs
View File

@ -1,4 +1,6 @@
/// log2 //! Common math functions.
/// Returns log2.
pub fn log2(x: usize) -> u32 { pub fn log2(x: usize) -> u32 {
if x <= 1 { if x <= 1 {
return 0; return 0;

2
util/src/misc.rs
View File

@ -1,3 +1,5 @@
//! Diff misc.
use common::*; use common::*;
#[derive(Debug,Clone,PartialEq,Eq)] #[derive(Debug,Clone,PartialEq,Eq)]

99
util/src/network/mod.rs
View File

@ -1,52 +1,53 @@
/// Network and general IO module. //! Network and general IO module.
/// Example usage for craeting a network service and adding an IO handler: //!
/// //! Example usage for craeting a network service and adding an IO handler:
/// ```rust //!
/// extern crate ethcore_util as util; //! ```rust
/// use util::*; //! extern crate ethcore_util as util;
/// //! use util::*;
/// struct MyHandler; //!
/// //! struct MyHandler;
/// #[derive(Clone)] //!
/// struct MyMessage { //! #[derive(Clone)]
/// data: u32 //! struct MyMessage {
/// } //! data: u32
/// //! }
/// impl NetworkProtocolHandler<MyMessage> for MyHandler { //!
/// fn initialize(&self, io: &NetworkContext<MyMessage>) { //! impl NetworkProtocolHandler<MyMessage> for MyHandler {
/// io.register_timer(0, 1000); //! fn initialize(&self, io: &NetworkContext<MyMessage>) {
/// } //! io.register_timer(0, 1000);
/// //! }
/// fn read(&self, io: &NetworkContext<MyMessage>, peer: &PeerId, packet_id: u8, data: &[u8]) { //!
/// println!("Received {} ({} bytes) from {}", packet_id, data.len(), peer); //! fn read(&self, io: &NetworkContext<MyMessage>, peer: &PeerId, packet_id: u8, data: &[u8]) {
/// } //! println!("Received {} ({} bytes) from {}", packet_id, data.len(), peer);
/// //! }
/// fn connected(&self, io: &NetworkContext<MyMessage>, peer: &PeerId) { //!
/// println!("Connected {}", peer); //! fn connected(&self, io: &NetworkContext<MyMessage>, peer: &PeerId) {
/// } //! println!("Connected {}", peer);
/// //! }
/// fn disconnected(&self, io: &NetworkContext<MyMessage>, peer: &PeerId) { //!
/// println!("Disconnected {}", peer); //! fn disconnected(&self, io: &NetworkContext<MyMessage>, peer: &PeerId) {
/// } //! println!("Disconnected {}", peer);
/// //! }
/// fn timeout(&self, io: &NetworkContext<MyMessage>, timer: TimerToken) { //!
/// println!("Timeout {}", timer); //! fn timeout(&self, io: &NetworkContext<MyMessage>, timer: TimerToken) {
/// } //! println!("Timeout {}", timer);
/// //! }
/// fn message(&self, io: &NetworkContext<MyMessage>, message: &MyMessage) { //!
/// println!("Message {}", message.data); //! fn message(&self, io: &NetworkContext<MyMessage>, message: &MyMessage) {
/// } //! println!("Message {}", message.data);
/// } //! }
/// //! }
/// fn main () { //!
/// let mut service = NetworkService::<MyMessage>::start(NetworkConfiguration::new()).expect("Error creating network service"); //! fn main () {
/// service.register_protocol(Arc::new(MyHandler), "myproto", &[1u8]); //! let mut service = NetworkService::<MyMessage>::start(NetworkConfiguration::new()).expect("Error creating network service");
/// //! service.register_protocol(Arc::new(MyHandler), "myproto", &[1u8]);
/// // Wait for quit condition //!
/// // ... //! // Wait for quit condition
/// // Drop the service //! // ...
/// } //! // Drop the service
/// ``` //! }
//! ```
mod host; mod host;
mod connection; mod connection;
mod handshake; mod handshake;

2
util/src/semantic_version.rs
View File

@ -1,3 +1,5 @@
//! Semantic version formatting and comparing.
/// A version value with strict meaning. Use `to_u32` to convert to a simple integer. /// A version value with strict meaning. Use `to_u32` to convert to a simple integer.
/// ///
/// # Example /// # Example

2
util/src/standard.rs
View File

@ -1,3 +1,5 @@
//! Std lib global reexports.
pub use std::io; pub use std::io;
pub use std::fs; pub use std::fs;
pub use std::str; pub use std::str;

2
util/src/trie/mod.rs
View File

@ -1,3 +1,5 @@
//! Trie interface and implementation.
/// TODO [Gav Wood] Please document me /// TODO [Gav Wood] Please document me
pub mod trietraits; pub mod trietraits;
pub mod standardmap; pub mod standardmap;

38
util/src/vector.rs
View File

@ -1,40 +1,4 @@
//! vector util functions //! Vector extensions.
use std::ptr;
/// TODO [debris] Please document me
pub trait InsertSlice<T> {
/// TODO [debris] Please document me
fn insert_slice(&mut self, index: usize, elements: &[T]);
}
/// based on `insert` function implementation from standard library
impl<T> InsertSlice<T> for Vec<T> {
fn insert_slice(&mut self, index: usize, elements: &[T]) {
let e_len = elements.len();
if e_len == 0 {
return;
}
let len = self.len();
assert!(index <= len);
// space for the new element
self.reserve(e_len);
unsafe {
{
let p = self.as_mut_ptr().offset(index as isize);
let ep = elements.as_ptr().offset(0);
// shift everything by e_len, to make space
ptr::copy(p, p.offset(e_len as isize), len - index);
// write new element
ptr::copy(ep, p, e_len);
}
self.set_len(len + e_len);
}
}
}
/// Returns len of prefix shared with elem /// Returns len of prefix shared with elem
/// ///