Parity as a library

Author: tomaka

Cargo.lock

@@ -41,7 +41,6 @@ ethcore-miner = { path = "miner" }
 ethcore-network = { path = "util/network" }
 ethcore-private-tx = { path = "ethcore/private-tx" }
 ethcore-service = { path = "ethcore/service" }
-ethcore-stratum = { path = "ethcore/stratum" }
 ethcore-sync = { path = "ethcore/sync" }
 ethcore-transaction = { path = "ethcore/transaction" }
 ethereum-types = "0.3"
@@ -109,6 +108,9 @@ slow-blocks = ["ethcore/slow-blocks"]
 secretstore = ["ethcore-secretstore"]
 final = ["parity-version/final"]
 
+[lib]
+path = "parity/lib.rs"
+
 [[bin]]
 path = "parity/main.rs"
 name = "parity"
@@ -131,6 +133,7 @@ members = [
 	"ethstore/cli",
 	"evmbin",
 	"miner",
+	"parity-clib",
 	"transaction-pool",
 	"whisper",
 	"whisper/cli",

Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+description = "C bindings for the Parity Ethereum client"
+name = "parity-clib"
+version = "1.11.0"
+license = "GPL-3.0"
+authors = ["Parity Technologies <[email protected]>"]
+
+[lib]
+name = "parity"
+crate-type = ["cdylib", "staticlib"]
+
+[dependencies]
+parity = { path = "../", default-features = false }
+
+[features]
+default = []
+final = ["parity/final"]

parity-clib/Cargo.toml

@@ -0,0 +1,83 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+// This file is part of Parity.
+
+// Parity is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity.  If not, see <http://www.gnu.org/licenses/>.
+
+#ifndef _PARITY_H_INCLUDED_
+#define _PARITY_H_INCLUDED_
+
+#include <cstddef>
+
+/// Parameters to pass to `parity_start`.
+struct ParityParams {
+    /// Configuration object, as handled by the `parity_config_*` functions.
+    /// Note that calling `parity_start` will destroy the configuration object (even on failure).
+    void *configuration;
+
+    /// Callback function to call when the client receives an RPC request to change its chain spec.
+    ///
+    /// The second and third parameters of the callback are the string pointer and length.
+    void (*on_client_restart_cb)(void *, const char *, size_t);
+
+    /// Custom parameter passed to the `on_client_restart_cb` callback as first parameter.
+    void *on_client_restart_cb_custom;
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Builds a new configuration object by parsing a list of CLI arguments.
+///
+/// The first two parameters are string pointers and string lengths. They must have a length equal
+/// to `len`. The strings don't need to be zero-terminated.
+///
+/// Returns 0 on success, and non-zero on error.
+///
+/// # Example
+///
+/// ```no_run
+/// void* cfg;
+/// const char *args[] = {"--light"};
+/// size_t str_lens[] = {7};
+/// if (parity_config_from_cli(args, str_lens, 1, &cfg) != 0) {
+///     return 1;
+/// }
+/// ```
+///
+int parity_config_from_cli(char const *const *args, size_t const *arg_lens, size_t len, void **out);
+
+/// Destroys a configuration object created earlier.
+///
+/// **Important**: You probably don't need to call this function. Calling `parity_start` destroys
+/// 				the configuration object as well (even on failure).
+void parity_config_destroy(void *);
+
+/// Starts the parity client in background threads. Returns a pointer to a struct that represents
+/// the running client.
+///
+/// **Important**: The configuration object passed inside `cfg` is destroyed when you
+/// 				call `parity_start` (even on failure).
+///
+/// Returns 0 on success, and non-zero on error.
+int parity_start(const ParityParams *, void **);
+
+/// Destroys the parity client created with `parity_start`.
+void parity_destroy(void *);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // include guard

parity-clib/parity.h

@@ -0,0 +1,132 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+// This file is part of Parity.
+
+// Parity is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Note that all the structs and functions here are documented in `parity.h`, to avoid
+//! duplicating documentation.
+
+extern crate parity;
+
+use std::os::raw::{c_char, c_void, c_int};
+use std::panic;
+use std::ptr;
+use std::slice;
+
+#[repr(C)]
+pub struct ParityParams {
+	pub configuration: *mut c_void,
+	pub on_client_restart_cb: extern "C" fn(*mut c_void, *const c_char, usize),
+	pub on_client_restart_cb_custom: *mut c_void,
+}
+
+#[no_mangle]
+pub extern fn parity_config_from_cli(args: *const *const c_char, args_lens: *const usize, len: usize, output: *mut *mut c_void) -> c_int {
+	unsafe {
+		panic::catch_unwind(|| {
+			*output = ptr::null_mut();
+
+			let args = {
+				let arg_ptrs = slice::from_raw_parts(args, len);
+				let arg_lens = slice::from_raw_parts(args_lens, len);
+
+				let mut args = Vec::with_capacity(len + 1);
+				args.push("parity".to_owned());
+
+				for (&arg, &len) in arg_ptrs.iter().zip(arg_lens.iter()) {
+					let string = slice::from_raw_parts(arg as *const u8, len);
+					match String::from_utf8(string.to_owned()) {
+						Ok(a) => args.push(a),
+						Err(_) => return 1,
+					};
+				}
+
+				args
+			};
+
+			match parity::Configuration::parse_cli(&args) {
+				Ok(mut cfg) => {
+					// Always disable the auto-updater when used as a library.
+					cfg.args.arg_auto_update = "none".to_owned();
+
+					let cfg = Box::into_raw(Box::new(cfg));
+					*output = cfg as *mut _;
+					0
+				},
+				Err(_) => {
+					1
+				},
+			}
+		}).unwrap_or(1)
+	}
+}
+
+#[no_mangle]
+pub extern fn parity_config_destroy(cfg: *mut c_void) {
+	unsafe {
+		let _ = panic::catch_unwind(|| {
+			let _cfg = Box::from_raw(cfg as *mut parity::Configuration);
+		});
+	}
+}
+
+#[no_mangle]
+pub extern fn parity_start(cfg: *const ParityParams, output: *mut *mut c_void) -> c_int {
+	unsafe {
+		panic::catch_unwind(|| {
+			*output = ptr::null_mut();
+			let cfg: &ParityParams = &*cfg;
+
+			let config = Box::from_raw(cfg.configuration as *mut parity::Configuration);
+
+			let on_client_restart_cb = {
+				struct Cb(extern "C" fn(*mut c_void, *const c_char, usize), *mut c_void);
+				unsafe impl Send for Cb {}
+				unsafe impl Sync for Cb {}
+				impl Cb {
+					fn call(&self, new_chain: String) {
+						let cb = self.0;
+						cb(self.1, new_chain.as_bytes().as_ptr() as *const _, new_chain.len())
+					}
+				}
+				let cb = Cb(cfg.on_client_restart_cb, cfg.on_client_restart_cb_custom);
+				move |new_chain: String| { cb.call(new_chain); }
+			};
+
+			let action = match parity::start(*config, on_client_restart_cb, || {}) {
+				Ok(action) => action,
+				Err(_) => return 1,
+			};
+
+			match action {
+				parity::ExecutionAction::Instant(Some(s)) => { println!("{}", s); 0 },
+				parity::ExecutionAction::Instant(None) => 0,
+				parity::ExecutionAction::Running(client) => {
+					*output = Box::into_raw(Box::<parity::RunningClient>::new(client)) as *mut c_void;
+					0
+				}
+			}
+		}).unwrap_or(1)
+	}
+}
+
+#[no_mangle]
+pub extern fn parity_destroy(client: *mut c_void) {
+	unsafe {
+		let _ = panic::catch_unwind(|| {
+			let client = Box::from_raw(client as *mut parity::RunningClient);
+			client.shutdown();
+		});
+	}
+}

parity-clib/src/lib.rs

@@ -37,7 +37,6 @@ use params::{SpecType, Pruning, Switch, tracing_switch_to_bool, fatdb_switch_to_
 use helpers::{to_client_config, execute_upgrades};
 use dir::Directories;
 use user_defaults::UserDefaults;
-use fdlimit;
 use ethcore_private_tx;
 use db;
 
@@ -178,8 +177,6 @@ fn execute_import_light(cmd: ImportBlockchain) -> Result<(), String> {
 	// load user defaults
 	let user_defaults = UserDefaults::load(&user_defaults_path)?;
 
-	fdlimit::raise_fd_limit();
-
 	// select pruning algorithm
 	let algorithm = cmd.pruning.to_algorithm(&user_defaults);
 
@@ -327,8 +324,6 @@ fn execute_import(cmd: ImportBlockchain) -> Result<(), String> {
 	// load user defaults
 	let mut user_defaults = UserDefaults::load(&user_defaults_path)?;
 
-	fdlimit::raise_fd_limit();
-
 	// select pruning algorithm
 	let algorithm = cmd.pruning.to_algorithm(&user_defaults);
 
@@ -518,8 +513,6 @@ fn start_client(
 	// load user defaults
 	let user_defaults = UserDefaults::load(&user_defaults_path)?;
 
-	fdlimit::raise_fd_limit();
-
 	// select pruning algorithm
 	let algorithm = pruning.to_algorithm(&user_defaults);
 

parity/blockchain.rs

@@ -198,6 +198,7 @@ macro_rules! usage {
 			}
 		}
 
+		/// Parsed command line arguments.
 		#[derive(Debug, PartialEq)]
 		pub struct Args {
 			$(

parity/cli/usage.rs

@@ -92,23 +92,30 @@ pub struct Execute {
 	pub cmd: Cmd,
 }
 
+/// Configuration for the Parity client.
 #[derive(Debug, PartialEq)]
 pub struct Configuration {
+	/// Arguments to be interpreted.
 	pub args: Args,
 }
 
 impl Configuration {
-	pub fn parse<S: AsRef<str>>(command: &[S]) -> Result<Self, ArgsError> {
-		let args = Args::parse(command)?;
-
+	/// Parses a configuration from a list of command line arguments.
+	///
+	/// # Example
+	///
+	/// ```
+	/// let _cfg = parity::Configuration::parse_cli(&["--light", "--chain", "koven"]).unwrap();
+	/// ```
+	pub fn parse_cli<S: AsRef<str>>(command: &[S]) -> Result<Self, ArgsError> {
 		let config = Configuration {
-			args: args,
+			args: Args::parse(command)?,
 		};
 
 		Ok(config)
 	}
 
-	pub fn into_command(self) -> Result<Execute, String> {
+	pub(crate) fn into_command(self) -> Result<Execute, String> {
 		let dirs = self.directories();
 		let pruning = self.args.arg_pruning.parse()?;
 		let pruning_history = self.args.arg_pruning_history;