This commit creates basic Rust bindings in the rust directory. The bindings are generated by generator/Rust.ml and generator/RustSys.ml. --- .gitignore | 10 + .ocamlformat | 4 + Makefile.am | 2 + configure.ac | 30 ++ generator/Makefile.am | 4 + generator/Rust.ml | 551 +++++++++++++++++++++++++++++++++++++ generator/Rust.mli | 20 ++ generator/RustSys.ml | 167 +++++++++++ generator/RustSys.mli | 19 ++ generator/generator.ml | 3 + rust/Cargo.toml | 49 ++++ rust/Makefile.am | 76 +++++ rust/cargo_test/Cargo.toml | 23 ++ rust/cargo_test/README.md | 3 + rust/cargo_test/src/lib.rs | 31 +++ rust/libnbd-sys/Cargo.toml | 32 +++ rust/libnbd-sys/build.rs | 26 ++ rust/libnbd-sys/src/lib.rs | 19 ++ rust/run-tests.sh.in | 24 ++ rust/src/error.rs | 157 +++++++++++ rust/src/handle.rs | 65 +++++ rust/src/lib.rs | 28 ++ rust/src/types.rs | 18 ++ rust/src/utils.rs | 23 ++ rustfmt.toml | 19 ++ scripts/git.orderfile | 10 + 26 files changed, 1413 insertions(+) create mode 100644 .ocamlformat create mode 100644 generator/Rust.ml create mode 100644 generator/Rust.mli create mode 100644 generator/RustSys.ml create mode 100644 generator/RustSys.mli create mode 100644 rust/Cargo.toml create mode 100644 rust/Makefile.am create mode 100644 rust/cargo_test/Cargo.toml create mode 100644 rust/cargo_test/README.md create mode 100644 rust/cargo_test/src/lib.rs create mode 100644 rust/libnbd-sys/Cargo.toml create mode 100644 rust/libnbd-sys/build.rs create mode 100644 rust/libnbd-sys/src/lib.rs create mode 100755 rust/run-tests.sh.in create mode 100644 rust/src/error.rs create mode 100644 rust/src/handle.rs create mode 100644 rust/src/lib.rs create mode 100644 rust/src/types.rs create mode 100644 rust/src/utils.rs create mode 100644 rustfmt.toml diff --git a/.gitignore b/.gitignore index e5304f1..6d4ba94 100644 --- a/.gitignore +++ b/.gitignore @@ -174,6 +174,16 @@ Makefile.in /python/nbd.py /python/run-python-tests /run +/rust/Cargo.lock +/rust/libnbd-sys/Cargo.lock +/rust/libnbd-sys/libnbd_version +/rust/libnbd-sys/src/generated.rs +/rust/src/async_bindings.rs +/rust/src/bindings.rs +/rust/target +/rust/cargo_test/Cargo.lock +/rust/cargo_test/target +/rust/run-tests.sh /sh/nbdsh /sh/nbdsh.1 /stamp-h1 diff --git a/.ocamlformat b/.ocamlformat new file mode 100644 index 0000000..7bfe155 --- /dev/null +++ b/.ocamlformat @@ -0,0 +1,4 @@ +profile = default +version = 0.25.1 +wrap-comments = true +margin = 78 diff --git a/Makefile.am b/Makefile.am index 243fabd..9f7707a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -28,6 +28,7 @@ EXTRA_DIST = \ README.md \ scripts/git.orderfile \ SECURITY \ + rustfmt.toml \ $(NULL) CLEANFILES += m4/*~ @@ -55,6 +56,7 @@ SUBDIRS = \ ocaml/tests \ golang \ golang/examples \ + rust \ interop \ fuzzing \ bash-completion \ diff --git a/configure.ac b/configure.ac index 0868e5d..ca8f809 100644 --- a/configure.ac +++ b/configure.ac @@ -613,6 +613,32 @@ AS_IF([test "x$enable_golang" != "xno"],[ ],[GOLANG=no]) AM_CONDITIONAL([HAVE_GOLANG],[test "x$GOLANG" != "xno"]) +dnl Rust. +AC_ARG_ENABLE([rust], + AS_HELP_STRING([--disable-rust], [disable Rust language bindings]), + [], + [enable_rust=yes]) +AS_IF([test "x$enable_rust" != "xno"],[ + AC_CHECK_PROG([CARGO],[cargo],[cargo],[no]) + AC_CHECK_PROG([RUSTFMT],[rustfmt],[rustfmt],[no]) + AS_IF([test "x$CARGO" != "xno"],[ + AC_MSG_CHECKING([if $CARGO is usable]) + AS_IF([ ( + cd $srcdir/rust/cargo_test && + $CARGO test 2>&AS_MESSAGE_LOG_FD 1>&2 && + $CARGO doc 2>&AS_MESSAGE_LOG_FD 1>&2 && + $CARGO fmt 2>&AS_MESSAGE_LOG_FD 1>&2 + ) ],[ + AC_MSG_RESULT([yes]) + ],[ + AC_MSG_RESULT([no]) + AC_MSG_WARN([Rust ($CARGO) is installed but not usable]) + CARGO=no + ]) + ]) +],[CARGO=no]) +AM_CONDITIONAL([HAVE_RUST],[test "x$CARGO" != "xno" -a "x$RUSTFMT" != "xno"]) + AC_MSG_CHECKING([for how to mark DSO non-deletable at runtime]) NODELETE= `$LD --help 2>&1 | grep -- "-z nodelete" >/dev/null` && \ @@ -643,6 +669,8 @@ AC_CONFIG_FILES([run], [chmod +x,-w run]) AC_CONFIG_FILES([sh/nbdsh], [chmod +x,-w sh/nbdsh]) +AC_CONFIG_FILES([rust/run-tests.sh], + [chmod +x,-w rust/run-tests.sh]) AC_CONFIG_FILES([Makefile bash-completion/Makefile @@ -657,6 +685,7 @@ AC_CONFIG_FILES([Makefile generator/Makefile golang/Makefile golang/examples/Makefile + rust/Makefile include/Makefile info/Makefile interop/Makefile @@ -717,6 +746,7 @@ echo echo "Language bindings:" echo feature "Go" test "x$HAVE_GOLANG_TRUE" = "x" +feature "Rust" test "x$HAVE_RUST_TRUE" = "x" feature "OCaml" test "x$HAVE_OCAML_TRUE" = "x" feature "Python" test "x$HAVE_PYTHON_TRUE" = "x" diff --git a/generator/Makefile.am b/generator/Makefile.am index c3d53b2..5e148be 100644 --- a/generator/Makefile.am +++ b/generator/Makefile.am @@ -60,6 +60,10 @@ sources = \ OCaml.ml \ GoLang.mli \ GoLang.ml \ + RustSys.mli \ + RustSys.ml \ + Rust.mli \ + Rust.ml \ generator.ml \ $(NULL) diff --git a/generator/Rust.ml b/generator/Rust.ml new file mode 100644 index 0000000..daf0e8a --- /dev/null +++ b/generator/Rust.ml @@ -0,0 +1,551 @@ +(* hey emacs, this is OCaml code: -*- tuareg -*- *) +(* nbd client library in userspace: generator + * Copyright Tage Johansson + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library 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 + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + *) + +(* Rust language bindings. *) + +open Printf +open API +open Utils + +(* The type for a set of names. *) +module NameSet = Set.Make (String) + +(* List of handle calls which should not be part of the public API. This could + for instance be `set_debug` and `set_debug_callback` which are handled + separately by the log crate *) +let hidden_handle_calls : NameSet.t = + NameSet.of_list + [ "get_debug"; "set_debug"; "set_debug_callback"; "clear_debug_callback" ] + +let print_rust_constant (name, value) = + pr "pub const %s: u32 = %d;\n" name value + +let print_rust_enum enum = + pr "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]\n"; + pr "#[repr(isize)]"; + pr "pub enum %s {\n" (camel_case enum.enum_prefix); + List.iter + (fun (name, num) -> pr " %s = %d,\n" (camel_case name) num) + enum.enums; + pr "}\n\n" + +(* Print a Rust struct for a set of flags. *) +let print_rust_flags { flag_prefix; flags } = + pr "bitflags! {\n"; + pr " #[repr(C)]\n"; + pr " #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]\n"; + pr " pub struct %s: u32 {\n" (camel_case flag_prefix); + List.iter + (fun (name, value) -> pr " const %s = %d;\n" name value) + flags; + pr " }\n"; + pr "}\n\n" + +(* Convert a string to upper snake case. *) +let to_upper_snake_case s = + s |> String.uppercase_ascii |> String.to_seq + |> Seq.filter_map (fun ch -> + match ch with '-' -> Some '_' | ':' -> None | ch -> Some ch) + |> String.of_seq + +(* Print metadata namespaces. *) +let print_metadata_namespace (ns, ctxts) = + pr "pub const NAMESPACE_%s: &[u8] = b\"%s:\";\n" (to_upper_snake_case ns) ns; + ctxts + |> List.iter (fun (ctxt, consts) -> + let s = ns ^ ":" ^ ctxt in + pr "pub const CONTEXT_%s_%s: &[u8] = b\"%s\";\n" + (to_upper_snake_case ns) + (to_upper_snake_case ctxt) + s; + consts + |> List.iter (fun (n, i) -> + pr "pub const %s: u32 = %d;\n" (to_upper_snake_case n) i)) + +(* Get the name of a rust argument. *) +let rust_arg_name : arg -> string = function + | Bool n + | Int n + | UInt n + | UIntPtr n + | UInt32 n + | Int64 n + | UInt64 n + | SizeT n + | String n + | StringList n + | Path n + | Fd n + | Enum (n, _) + | Flags (n, _) + | SockAddrAndLen (n, _) + | BytesIn (n, _) + | BytesPersistIn (n, _) + | BytesOut (n, _) + | BytesPersistOut (n, _) + | Closure { cbname = n } -> + n + +(* Get the name of a rust optional argument. *) +let rust_optarg_name : optarg -> string = function + | OClosure { cbname = n } | OFlags (n, _, _) -> n + +(* Get the name of a Rust closure argument. *) +let rust_cbarg_name : cbarg -> string = function + | CBInt n | CBUInt n | CBInt64 n | CBUInt64 n | CBString n | CBBytesIn (n, _) + -> + n + | CBArrayAndLen (arg, _) | CBMutable arg -> rust_arg_name arg + +(* Get the Rust type for an argument. *) +let rec rust_arg_type : arg -> string = function + | Bool _ -> "bool" + | Int _ -> "c_int" + | UInt _ -> "c_uint" + | UIntPtr _ -> "usize" + | UInt32 _ -> "u32" + | Int64 _ -> "i64" + | UInt64 _ -> "u64" + | SizeT _ -> "usize" + | String _ -> "impl Into<Vec<u8>>" + | SockAddrAndLen _ -> "SocketAddr" + | StringList _ -> "impl IntoIterator<Item = impl AsRef<[u8]>>" + | Path _ -> "impl Into<PathBuf>" + | Enum (_, { enum_prefix = name }) | Flags (_, { flag_prefix = name }) -> + camel_case name + | Fd _ -> "OwnedFd" + | BytesIn _ -> "&[u8]" + | BytesOut _ -> "&mut [u8]" + | BytesPersistIn _ -> "&'static [u8]" + | BytesPersistOut _ -> "&'static mut [u8]" + | Closure { cbargs } -> "impl " ^ rust_closure_trait cbargs + +(* Get the Rust closure trait for a callback, That is `Fn*(...) -> ...)`. *) +and rust_closure_trait ?(lifetime = Some "'static") cbargs : string = + let rust_cbargs = String.concat ", " (List.map rust_cbarg_type cbargs) + and lifetime_constraint = + match lifetime with None -> "" | Some x -> " + " ^ x + in + "FnMut(" ^ rust_cbargs ^ ") -> c_int + Send + Sync" ^ lifetime_constraint + +(* Get the Rust type for a callback argument. *) +and rust_cbarg_type : cbarg -> string = function + | CBInt n -> rust_arg_type (Int n) + | CBUInt n -> rust_arg_type (UInt n) + | CBInt64 n -> rust_arg_type (Int64 n) + | CBUInt64 n -> rust_arg_type (UInt64 n) + | CBString n -> "&[u8]" + | CBBytesIn (n1, n2) -> rust_arg_type (BytesIn (n1, n2)) + | CBArrayAndLen (elem, _) -> "&[" ^ rust_arg_type elem ^ "]" + | CBMutable arg -> "&mut " ^ rust_arg_type arg + +(* Get the type of a rust optional argument. *) +let rust_optarg_type : optarg -> string = function + | OClosure x -> sprintf "Option<%s>" (rust_arg_type (Closure x)) + | OFlags (name, flags, _) -> + sprintf "Option<%s>" (rust_arg_type (Flags (name, flags))) + +(* Given an argument, produce a list of names for arguments in FFI functions + corresponding to that argument. Most arguments will just produce one name + for one FFI argument, but for example [BytesIn] requires two separate FFI + arguments hence a list is produced. *) +let ffi_arg_names : arg -> string list = function + | Bool n + | Int n + | UInt n + | UIntPtr n + | UInt32 n + | Int64 n + | UInt64 n + | SizeT n + | String n + | StringList n + | Path n + | Fd n + | Enum (n, _) + | Flags (n, _) + | Closure { cbname = n } -> + [ n ^ "_ffi" ] + | SockAddrAndLen (n1, n2) + | BytesIn (n1, n2) + | BytesPersistIn (n1, n2) + | BytesOut (n1, n2) + | BytesPersistOut (n1, n2) -> + [ n1 ^ "_ffi"; n2 ^ "_ffi" ] + +let ffi_optarg_name : optarg -> string = function + | OClosure { cbname = name } | OFlags (name, _, _) -> name ^ "_ffi" + +(* Given a closure argument, produce a list of names used by FFI functions for + that particular argument. Most closure arguments will just produce one FFI + argument, but for instance [CBArrayAndLen] will produce two, hence we + return a list. *) +let ffi_cbarg_names : cbarg -> string list = function + | CBInt n | CBUInt n | CBInt64 n | CBUInt64 n | CBString n -> [ n ^ "_ffi" ] + | CBBytesIn (n1, n2) -> [ n1 ^ "_ffi"; n2 ^ "_ffi" ] + | CBArrayAndLen (arg, len) -> [ rust_arg_name arg ^ "_ffi"; len ^ "_ffi" ] + | CBMutable arg -> [ rust_arg_name arg ^ "_ffi" ] + +(* Given a closure argument, produce a list of types used by FFI functions for + that particular argument. Most closure arguments will just produce one FFI + argument, but for instance [CBArrayAndLen] will produce two, hence we + return a list. *) +let ffi_cbarg_types : cbarg -> string list = function + | CBInt _ -> [ "c_int" ] + | CBUInt _ -> [ "c_uint" ] + | CBInt64 _ -> [ "i64" ] + | CBUInt64 _ -> [ "u64" ] + | CBString _ -> [ "*const c_char" ] + | CBBytesIn _ -> [ "*const c_void"; "usize" ] + | CBArrayAndLen (UInt32 _, _) -> [ "*mut u32"; "usize" ] + | CBArrayAndLen _ -> + failwith + "generator/Rust.ml: in ffi_cbarg_types: Unsupported type of array \ + element." + | CBMutable (Int _) -> [ "*mut c_int" ] + | CBMutable _ -> + failwith + "generator/Rust.ml: in ffi_cbarg_types: Unsupported type of mutable \ + argument." + +(* Return type for a Rust function. *) +let rust_ret_type call : string = + let core_type = + match call.ret with + | RBool -> "bool" + | RStaticString -> "&'static [u8]" + | RErr -> "()" + | RFd -> "RawFd" + | RInt -> "c_uint" + | RInt64 -> "u64" + | RCookie -> "Cookie" + | RSizeT -> "usize" + | RString -> "Vec<u8>" + | RUInt -> "c_uint" + | RUIntPtr -> "usize" + | RUInt64 -> "u64" + | REnum { enum_prefix = name } | RFlags { flag_prefix = name } -> + camel_case name + in + if call.may_set_error then sprintf "Result<%s>" core_type else core_type + +(* Given an argument ([arg : arg]), print Rust code for variable declarations + for all FFI arguments corresponding to [arg]. That is, for each + `<FFI_NAME>` in [ffi_arg_names arg], print `let <FFI_NAME> = <...>;`. + Assuming that a variable with name [rust_arg_name arg] and type + [rust_arg_type arg] exists in scope. *) +let rust_arg_to_ffi arg = + let rust_name = rust_arg_name arg in + let ffi_names = ffi_arg_names arg in + match arg with + | Bool _ | Int _ | UInt _ | UIntPtr _ | UInt32 _ | Int64 _ | UInt64 _ + | SizeT _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + pr "let %s = %s;\n" ffi_name rust_name + | Enum _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + pr "let %s = %s as c_int;\n" ffi_name rust_name + | Flags _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + pr "let %s = %s.bits();\n" ffi_name rust_name + | SockAddrAndLen _ -> + let ffi_addr_name, ffi_len_name = + match ffi_names with [ x; y ] -> (x, y) | _ -> assert false + in + pr "let %s_os = OsSocketAddr::from(%s);\n" rust_name rust_name; + pr "let %s = %s_os.as_ptr();\n" ffi_addr_name rust_name; + pr "let %s = %s_os.len();\n" ffi_len_name rust_name + | String _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + pr + "let %s_buf = CString::new(%s.into()).map_err(|e| Error::from(e))?;\n" + rust_name rust_name; + pr "let %s = %s_buf.as_ptr();\n" ffi_name rust_name + | Path _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + pr "let %s_buf = " rust_name; + pr "CString::new(%s.into().into_os_string().into_vec())" rust_name; + pr ".map_err(|e| Error::from(e))?;\n"; + pr "let %s = %s_buf.as_ptr();\n" ffi_name rust_name + | StringList _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + (* Create a `Vec` with the arguments as `CString`s. This will copy every + string and thereby require some extra heap allocations. *) + pr "let %s_c_strs: Vec<CString> = " ffi_name; + pr "%s.into_iter()" rust_name; + pr ".map(|x| CString::new(x.as_ref())"; + pr ".map_err(|e| Error::from(e.to_string())))"; + pr ".collect::<Result<Vec<CString>>>()?;\n"; + (* Create a vector of pointers to all of these `CString`s. For some + reason, the C API hasn't marked the pointers as const, so we use + `cast_mut` and `as_mut_ptr` here even though the strings shouldn't be + modified. *) + pr "let mut %s_ptrs: Vec<*mut c_char> = \n" ffi_name; + pr " %s_c_strs.iter().map(|x| x.as_ptr().cast_mut()).collect();\n" + ffi_name; + (* Add a null pointer to mark the end of the list. *) + pr "%s_ptrs.push(ptr::null_mut());\n" ffi_name; + pr "let %s = %s_ptrs.as_mut_ptr();\n" ffi_name ffi_name + | BytesIn _ | BytesPersistIn _ -> + let ffi_buf_name, ffi_len_name = + match ffi_names with [ x; y ] -> (x, y) | _ -> assert false + in + pr "let %s = %s.as_ptr() as *const c_void;\n" ffi_buf_name rust_name; + pr "let %s = %s.len();\n" ffi_len_name rust_name + | BytesOut _ | BytesPersistOut _ -> + let ffi_buf_name, ffi_len_name = + match ffi_names with [ x; y ] -> (x, y) | _ -> assert false + in + pr "let %s = %s.as_mut_ptr() as *mut c_void;\n" ffi_buf_name rust_name; + pr "let %s = %s.len();\n" ffi_len_name rust_name + | Fd _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + pr "let %s = %s.as_raw_fd();\n" ffi_name rust_name + | Closure _ -> + let ffi_name = match ffi_names with [ x ] -> x | _ -> assert false in + pr "let %s = unsafe { crate::bindings::%s_to_raw(%s) };\n" ffi_name + rust_name rust_name + +(* Same as [rust_arg_to_ffi] but for optional arguments. *) +let rust_optarg_to_ffi arg = + let rust_name = rust_optarg_name arg in + let ffi_name = ffi_optarg_name arg in + match arg with + | OClosure { cbname } -> + pr "let %s = match %s {\n" ffi_name rust_name; + pr " Some(f) => unsafe { crate::bindings::%s_to_raw(f) },\n" + rust_name; + pr " None => sys::nbd_%s_callback { " cbname; + pr "callback: None, "; + pr "free: None, "; + pr "user_data: ptr::null_mut() "; + pr "},\n"; + pr "};\n" + | OFlags (_, { flag_prefix }, _) -> + let flags_type = camel_case flag_prefix in + pr "let %s = %s.unwrap_or(%s::empty()).bits();\n" ffi_name rust_name + flags_type + +(* Given a closure argument ([x : cbarg]), print Rust code to create a + variable with name [rust_cbarg_name x] of type [rust_cbarg_type x]. + Assuming that variables with names from [ffi_cbarg_names x] exists in + scope. *) +let ffi_cbargs_to_rust cbarg = + let ffi_names = ffi_cbarg_names cbarg in + pr "let %s: %s = " (rust_cbarg_name cbarg) (rust_cbarg_type cbarg); + (match (cbarg, ffi_names) with + | (CBInt _ | CBUInt _ | CBInt64 _ | CBUInt64 _), [ ffi_name ] -> + pr "%s" ffi_name + | CBString _, [ ffi_name ] -> pr "CStr::from_ptr(%s).to_bytes()" ffi_name + | CBBytesIn _, [ ffi_buf_name; ffi_len_name ] -> + pr "slice::from_raw_parts(%s as *const u8, %s)" ffi_buf_name + ffi_len_name + | CBArrayAndLen (UInt32 _, _), [ ffi_arr_name; ffi_len_name ] -> + pr "slice::from_raw_parts(%s, %s)" ffi_arr_name ffi_len_name + | CBArrayAndLen _, [ _; _ ] -> + failwith + "generator/Rust.ml: in ffi_cbargs_to_rust: Unsupported type of array \ + element." + | CBMutable (Int _), [ ffi_name ] -> pr "%s.as_mut().unwrap()" ffi_name + | CBMutable _, [ _ ] -> + failwith + "generator/Rust.ml: in ffi_cbargs_to_rust: Unsupported type of \ + mutable argument." + | _, _ -> + failwith + "generator/Rust.ml: In ffi_cbargs_to_rust: bad number of ffi \ + arguments."); + pr ";\n" + +(* Print Rust code for converting a return value from an FFI call to a Rusty + return value. In other words, given [x : ret], this functions print a Rust + expression with type [rust_ret_type x], with a free variable [ffi_ret] with + the return value from the FFI call. *) +let ffi_ret_to_rust call = + let ret_type = rust_ret_type call in + let pure_expr = + match call.ret with + | RBool -> "ffi_ret != 0" + | RErr -> "()" + | RInt -> "TryInto::<u32>::try_into(ffi_ret).unwrap()" + | RInt64 -> "TryInto::<u64>::try_into(ffi_ret).unwrap()" + | RSizeT -> "TryInto::<usize>::try_into(ffi_ret).unwrap()" + | RCookie -> "Cookie(ffi_ret.try_into().unwrap())" + | RFd -> "ffi_ret as RawFd" + | RStaticString -> "unsafe { CStr::from_ptr(ffi_ret) }.to_bytes()" + | RString -> + "{ let res = \n" + ^ " unsafe { CStr::from_ptr(ffi_ret) }.to_owned().into_bytes();\n" + ^ "unsafe { libc::free(ffi_ret.cast()); }\n" ^ "res }" + | RFlags { flag_prefix } -> + sprintf "%s::from_bits(ffi_ret).unwrap()" ret_type + | RUInt | RUIntPtr | RUInt64 -> sprintf "ffi_ret as %s" ret_type + | REnum _ -> + (* We know that each enum is represented by an isize, hence this + transmute is safe. *) + sprintf "unsafe { mem::transmute::<isize, %s>(ffi_ret as isize) }" + ret_type + in + if call.may_set_error then ( + (match call.ret with + | RBool | RErr | RInt | RFd | RInt64 | RCookie | RSizeT -> + pr "if ffi_ret < 0 {\n"; + pr " Err(unsafe { Error::get_error(self.raw_handle()) })\n"; + pr "}\n" + | RStaticString | RString -> + pr "if ffi_ret.is_null() {\n"; + pr " Err(unsafe { Error::get_error(self.raw_handle()) })\n"; + pr "}\n" + | RUInt | RUIntPtr | RUInt64 | REnum _ | RFlags _ -> + failwith "In ffi_ret_to_rust: Return type cannot be an error."); + pr "else { Ok(%s) }\n" pure_expr) + else pr "%s\n" pure_expr + +(* This function prints a rust function which converts a rust closure to a + (`repr(C)`) struct containing the function pointer, a `*mut c_void` for the + closure data, and a free function for the closure data. This struct is what + will be sent to a C function taking the closure as an argument. In fact, + the struct itself is generated by rust-bindgen. *) +let print_rust_closure_to_raw_fn { cbname; cbargs } = + let closure_trait = rust_closure_trait cbargs ~lifetime:None in + let ffi_cbargs_names = List.flatten (List.map ffi_cbarg_names cbargs) in + let ffi_cbargs_types = List.flatten (List.map ffi_cbarg_types cbargs) in + let rust_cbargs_names = List.map rust_cbarg_name cbargs in + pr "pub(crate) unsafe fn %s_to_raw<F>(f: F) -> sys::nbd_%s_callback\n" + cbname cbname; + pr " where F: %s\n" closure_trait; + pr "{\n"; + pr + " unsafe extern \"C\" fn call_closure<F>(data: *mut c_void, %s) -> \ + c_int\n" + (String.concat ", " + (List.map2 (sprintf "%s: %s") ffi_cbargs_names ffi_cbargs_types)); + pr " where F: %s\n" closure_trait; + pr " {\n"; + pr " let callback_ptr = data as *mut F;\n"; + pr " let callback = &mut *callback_ptr;\n"; + List.iter ffi_cbargs_to_rust cbargs; + pr " callback(%s)\n" (String.concat ", " rust_cbargs_names); + pr " }\n"; + pr " let callback_data = Box::into_raw(Box::new(f));\n"; + pr " sys::nbd_%s_callback {\n" cbname; + pr " callback: Some(call_closure::<F>),\n"; + pr " user_data: callback_data as *mut _,\n"; + pr " free: Some(utils::drop_data::<F>),\n"; + pr " }\n"; + pr "}\n"; + pr "\n" + +(* Print the comment for a rust function for a handle call. *) +let print_rust_handle_call_comment call = + (* Print comments. *) + if call.shortdesc <> String.empty then + pr "/// %s\n" + (String.concat "\n/// " (String.split_on_char '\n' call.shortdesc)); + if call.longdesc <> String.empty then ( + (* If a short comment was printed, print a blank comment line befor the + long description. *) + if call.shortdesc <> String.empty then pr "/// \n"; + (* Print all lines of the long description. Since Rust comments are + supposed to be Markdown, all indented lines will be treated as code + blocks. Hence we trim all lines. Also brackets ("[" and "]") must be + escaped. *) + List.iter + (fun line -> + let unindented = String.trim line in + let escaped = + Str.global_replace (Str.regexp {|\(\[\|\]\)|}) {|\\\1|} unindented + in + pr "/// %s\n" escaped) + (pod2text call.longdesc)) + +(* Print a Rust expression which converts Rust like arguments to FFI like + arguments, makes a call on the raw FFI handle, and converts the return + value to a Rusty type. The expression assumes that variables with name + `rust_arg_name arg` for all `arg` in `call.args` exists in scope. *) +let print_ffi_call name handle call = + let ffi_args_names = + List.flatten (List.map ffi_arg_names call.args) + @ List.map ffi_optarg_name call.optargs + in + pr "{\n"; + pr " // Convert all arguments to FFI-like types.\n"; + List.iter rust_arg_to_ffi call.args; + List.iter rust_optarg_to_ffi call.optargs; + pr "\n"; + pr " // Call the FFI-function.\n"; + pr " let ffi_ret = unsafe { sys::nbd_%s(%s, %s) };\n" name handle + (String.concat ", " ffi_args_names); + pr "\n"; + pr " // Convert the result to something more rusty.\n"; + ffi_ret_to_rust call; + pr "}\n" + +(* Print the Rust function for a handle call. Note that this is a "method" on + the `Handle` struct. So the printed Rust function should be in an `impl + Handle {` block. *) +let print_rust_handle_method (name, call) = + let rust_args_names = + List.map rust_arg_name call.args @ List.map rust_optarg_name call.optargs + and rust_args_types = + List.map rust_arg_type call.args @ List.map rust_optarg_type call.optargs + in + let rust_args = + String.concat ", " + (List.map2 (sprintf "%s: %s") rust_args_names rust_args_types) + in + print_rust_handle_call_comment call; + (* Print visibility modifier. *) + if NameSet.mem name hidden_handle_calls then ( + (* If this is hidden to the public API, it might be used only if some feature + * is active, and we don't want a unused-warning. *) + pr "#[allow(unused)]\n"; + pr "pub(crate) ") + else pr "pub "; + pr "fn %s(&self, %s) -> %s\n" name rust_args (rust_ret_type call); + print_ffi_call name "self.handle" call; + pr "\n" + +let print_rust_imports () = + pr "use bitflags::bitflags;\n"; + pr "use crate::{*, types::*};\n"; + pr "use os_socketaddr::OsSocketAddr;\n"; + pr "use std::ffi::*;\n"; + pr "use std::mem;\n"; + pr "use std::net::SocketAddr;\n"; + pr "use std::os::fd::{AsRawFd, OwnedFd, RawFd};\n"; + pr "use std::os::unix::prelude::*;\n"; + pr "use std::path::PathBuf;\n"; + pr "use std::ptr;\n"; + pr "use std::slice;\n"; + pr "\n" + +let generate_rust_bindings () = + generate_header CStyle ~copyright:"Tage Johansson"; + pr "\n"; + print_rust_imports (); + List.iter print_rust_constant constants; + pr "\n"; + List.iter print_rust_enum all_enums; + List.iter print_rust_flags all_flags; + List.iter print_metadata_namespace metadata_namespaces; + List.iter print_rust_closure_to_raw_fn all_closures; + pr "impl Handle {\n"; + List.iter print_rust_handle_method handle_calls; + pr "}\n\n" diff --git a/generator/Rust.mli b/generator/Rust.mli new file mode 100644 index 0000000..450e4ca --- /dev/null +++ b/generator/Rust.mli @@ -0,0 +1,20 @@ +(* nbd client library in userspace: generator + * Copyright Tage Johansson + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library 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 + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + *) + +(* Print all flag-structs, enums, constants and handle calls in Rust code. *) +val generate_rust_bindings : unit -> unit diff --git a/generator/RustSys.ml b/generator/RustSys.ml new file mode 100644 index 0000000..2a50a40 --- /dev/null +++ b/generator/RustSys.ml @@ -0,0 +1,167 @@ +(* hey emacs, this is OCaml code: -*- tuareg -*- *) +(* nbd client library in userspace: generator + * Copyright Tage Johansson + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library 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 + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + *) + +(* Low level Rust bindings for the libnbd-sys crate. *) + +open Printf +open API +open Utils + +(** A list of the argument types corresponding to an [arg]. *) +let arg_types : arg -> string list = function + | Bool n -> [ "bool" ] + | Int n | Fd n | Enum (n, _) -> [ "c_int" ] + | UInt n -> [ "c_uint" ] + | UIntPtr n -> [ "uintptr_t" ] + | SizeT n -> [ "size_t" ] + | UInt32 n | Flags (n, _) -> [ "u32" ] + | Int64 n -> [ "i64" ] + | UInt64 n -> [ "u64" ] + | String n | Path n -> [ "*const c_char" ] + | SockAddrAndLen (n1, n2) -> [ "*const sockaddr"; "socklen_t" ] + | StringList n -> [ "*mut *mut c_char" ] + | BytesIn (n1, n2) | BytesPersistIn (n1, n2) -> [ "*const c_void"; "usize" ] + | BytesOut (n1, n2) | BytesPersistOut (n1, n2) -> [ "*mut c_void"; "usize" ] + | Closure { cbname } -> [ sprintf "nbd_%s_callback" cbname ] + +(** The type of an optional argument. *) +let optarg_type : optarg -> string = function + | OClosure { cbname } -> sprintf "nbd_%s_callback" cbname + | OFlags _ -> "u32" + +(** The types of arguments corresponding to a [cbarg]. *) +let cbarg_types : cbarg -> string list = function + | CBInt n -> arg_types (Int n) + | CBUInt n -> arg_types (UInt n) + | CBInt64 n -> arg_types (Int64 n) + | CBUInt64 n -> arg_types (UInt64 n) + | CBString n -> arg_types (String n) + | CBBytesIn (n1, n2) -> arg_types (BytesIn (n1, n2)) + | CBMutable arg -> arg_types arg |> List.map (fun x -> "*mut " ^ x) + | CBArrayAndLen (elem, _) -> + let elem_type = + match arg_types elem with + | [ x ] -> x + | _ -> failwith "Bad array element type" + in + [ sprintf "*mut %s" elem_type; "usize" ] + +(** Get a return type. *) +let ret_type : ret -> string = function + | RBool -> "c_int" + | RStaticString -> "*const c_char" + | RInt | RErr | RFd | REnum _ -> "c_int" + | RInt64 | RCookie -> "i64" + | RSizeT -> "isize" + | RString -> "*mut c_char" + | RUInt -> "c_uint" + | RUInt64 -> "u64" + | RUIntPtr -> "uintptr_t" + | RFlags _ -> "u32" + +(** The names of all arguments corresponding to an [arg]. *) +let arg_names : arg -> string list = function + | Bool n + | Int n + | UInt n + | UIntPtr n + | UInt32 n + | Int64 n + | UInt64 n + | SizeT n + | String n + | StringList n + | Path n + | Fd n + | Enum (n, _) + | Flags (n, _) + | Closure { cbname = n } -> + [ n ] + | SockAddrAndLen (n1, n2) + | BytesIn (n1, n2) + | BytesPersistIn (n1, n2) + | BytesOut (n1, n2) + | BytesPersistOut (n1, n2) -> + [ n1; n2 ] + +(** The name of an optional argument. *) +let optarg_name : optarg -> string = function + | OClosure { cbname = name } | OFlags (name, _, _) -> name + +(** Print the struct for a closure. *) +let print_closure_struct { cbname; cbargs } = + pr "#[repr(C)]\n"; + pr "#[derive(Debug, Clone, Copy)]\n"; + pr "pub struct nbd_%s_callback {\n" cbname; + pr " pub callback: \n"; + pr " Option<unsafe extern \"C\" fn(*mut c_void, %s) -> c_int>,\n" + (cbargs |> List.map cbarg_types |> List.flatten |> String.concat ", "); + pr " pub user_data: *mut c_void,\n"; + pr " pub free: Option<unsafe extern \"C\" fn(*mut c_void)>,\n"; + pr "}\n" + +(** Print an "extern definition" for a handle call. *) +let print_handle_call (name, call) = + let args_names = + (call.args |> List.map arg_names |> List.flatten) + @ (call.optargs |> List.map optarg_name) + in + let args_types = + (call.args |> List.map arg_types |> List.flatten) + @ (call.optargs |> List.map optarg_type) + in + pr "pub fn nbd_%s(handle: *mut nbd_handle, %s) -> %s;\n" name + (List.map2 (fun n ty -> sprintf "%s: %s" n ty) args_names args_types + |> String.concat ", ") + (ret_type call.ret) + +(** Print a definition of the "nbd_handle" type. *) +let print_nbd_handle () = + pr "#[repr(C)]\n"; + pr "#[derive(Debug, Clone, Copy)]\n"; + pr "pub struct nbd_handle {\n"; + pr " _unused: [u8; 0],\n"; + pr "}\n"; + pr "\n" + +(** Print some more "extern definitions". *) +let print_more_defs () = + pr "extern \"C\" {\n"; + pr "pub fn nbd_get_error() -> *const c_char;\n"; + pr "pub fn nbd_get_errno() -> c_int;\n"; + pr "pub fn nbd_create() -> *mut nbd_handle;\n"; + pr "pub fn nbd_close(h: *mut nbd_handle);\n"; + pr "}\n"; + pr "\n" + +let print_imports () = + pr "use libc::*;\n"; + pr "use std::ffi::c_void;\n"; + pr "\n" + +let generate_rust_sys_bindings () = + generate_header CStyle ~copyright:"Tage Johansson"; + pr "\n"; + print_imports (); + print_nbd_handle (); + print_more_defs (); + all_closures |> List.iter print_closure_struct; + pr "extern \"C\" {\n"; + handle_calls |> List.iter print_handle_call; + pr "}\n\n" diff --git a/generator/RustSys.mli b/generator/RustSys.mli new file mode 100644 index 0000000..de66bdc --- /dev/null +++ b/generator/RustSys.mli @@ -0,0 +1,19 @@ +(* nbd client library in userspace: generator + * Copyright Tage Johansson + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library 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 + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + *) + +val generate_rust_sys_bindings : unit -> unit diff --git a/generator/generator.ml b/generator/generator.ml index c73824e..c62b0c4 100644 --- a/generator/generator.ml +++ b/generator/generator.ml @@ -61,3 +61,6 @@ let () = output_to "golang/closures.go" GoLang.generate_golang_closures_go; output_to "golang/wrappers.go" GoLang.generate_golang_wrappers_go; output_to "golang/wrappers.h" GoLang.generate_golang_wrappers_h; + + output_to ~formatter:(Some Rustfmt) "rust/libnbd-sys/src/generated.rs" RustSys.generate_rust_sys_bindings; + output_to ~formatter:(Some Rustfmt) "rust/src/bindings.rs" Rust.generate_rust_bindings; diff --git a/rust/Cargo.toml b/rust/Cargo.toml new file mode 100644 index 0000000..c745972 --- /dev/null +++ b/rust/Cargo.toml @@ -0,0 +1,49 @@ +# nbd client library in userspace +# Copyright Tage Johansson +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library 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 +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +[workspace] + +[workspace.package] +authors = ["Tage Johansson"] +version = "0.1.0" +edition = "2021" +description = "Rust bindings for libnbd, a client library for controlling block devices over a network." +license = "LGPL-2.1-only" +keywords = ["libnbd", "block-device", "network"] +categories = ["api-bindings", "emulators", "virtualization"] + +[package] +name = "libnbd" +authors.workspace = true +version.workspace = true +edition.workspace = true +description.workspace = true +license.workspace = true +keywords.workspace = true +categories.workspace = true + +[dependencies] +libnbd-sys = { path = "libnbd-sys" } +bitflags = "2.3.1" +errno = "0.3.1" +os_socketaddr = "0.2.4" +thiserror = "1.0.40" +log = { version = "0.4.19", optional = true } +libc = "0.2.147" + +[features] +default = ["log"] diff --git a/rust/Makefile.am b/rust/Makefile.am new file mode 100644 index 0000000..b39bd32 --- /dev/null +++ b/rust/Makefile.am @@ -0,0 +1,76 @@ +# nbd client library in userspace +# Copyright Tage Johansson +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library 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 +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +include $(top_srcdir)/subdir-rules.mk + +generator_built = \ + libnbd-sys/src/generated.rs \ + src/bindings.rs \ + $(NULL) + +source_files = \ + $(generator_built) \ + Cargo.toml \ + src/lib.rs \ + src/error.rs \ + src/handle.rs \ + src/types.rs \ + src/utils.rs \ + libnbd-sys/Cargo.toml \ + libnbd-sys/build.rs \ + libnbd-sys/src/lib.rs \ + cargo_test/Cargo.toml \ + cargo_test/src/lib.rs \ + cargo_test/README.md \ + run-tests.sh.in \ + $(NULL) + +EXTRA_DIST = \ + $(source_files) \ + $(NULL) + +if HAVE_RUST + +all-local: libnbd-sys/libnbd_version target/debug/liblibnbd.rlib \ + target/doc/libnbd/index.html + +libnbd-sys/libnbd_version: Makefile + rm -f libnbd-sys/libnbd_version.t + $(abs_top_builddir)/run echo $(VERSION) > libnbd-sys/libnbd_version.t + mv libnbd-sys/libnbd_version.t libnbd-sys/libnbd_version + +target/debug/liblibnbd.rlib: $(source_files) + $(abs_top_builddir)/run $(CARGO) build + +target/doc/libnbd/index.html: $(source_files) + $(abs_top_builddir)/run $(CARGO) doc + +TESTS_ENVIRONMENT = \ + LIBNBD_DEBUG=1 \ + $(MALLOC_CHECKS) \ + abs_top_srcdir=$(abs_top_srcdir) \ + $(NULL) +LOG_COMPILER = $(top_builddir)/run +TESTS = run-tests.sh + +clean-local: + $(CARGO) clean + $(CARGO) clean --manifest-path cargo_test/Cargo.toml + +endif + +CLEANFILES += libnbd-sys/libnbd_version diff --git a/rust/cargo_test/Cargo.toml b/rust/cargo_test/Cargo.toml new file mode 100644 index 0000000..9f9d478 --- /dev/null +++ b/rust/cargo_test/Cargo.toml @@ -0,0 +1,23 @@ +# nbd client library in userspace +# Copyright Tage Johansson +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library 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 +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +[workspace] + +[package] +name = "cargo_test" +edition = "2021" +version = "0.1.0" diff --git a/rust/cargo_test/README.md b/rust/cargo_test/README.md new file mode 100644 index 0000000..f80646b --- /dev/null +++ b/rust/cargo_test/README.md @@ -0,0 +1,3 @@ +The solely purpose of this directory is to serve as a test crate for checking if Cargo is useable. +`cargo test`, `cargo doc` and `cargo fmt` are run in the Autoconf script in this directory. If any of the commands failes, +Cargo is assumed not to be useable and the Rust bindings will be disabled. diff --git a/rust/cargo_test/src/lib.rs b/rust/cargo_test/src/lib.rs new file mode 100644 index 0000000..a5cbb84 --- /dev/null +++ b/rust/cargo_test/src/lib.rs @@ -0,0 +1,31 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +/// A dummy test function which adds one to an 32-bit integer. +pub fn add_one(i: i32) -> i32 { + i + 1 +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_add_one() { + assert_eq!(add_one(42), 43); + } +} diff --git a/rust/libnbd-sys/Cargo.toml b/rust/libnbd-sys/Cargo.toml new file mode 100644 index 0000000..3fa581f --- /dev/null +++ b/rust/libnbd-sys/Cargo.toml @@ -0,0 +1,32 @@ +# nbd client library in userspace +# Copyright Tage Johansson +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library 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 +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +[package] +name = "libnbd-sys" +version.workspace = true +edition.workspace = true +description.workspace = true +license.workspace = true +keywords.workspace = true +categories.workspace = true +links = "nbd" + +[build-dependencies] +pkg-config = "0.3.27" + +[dependencies] +libc = "0.2.147" diff --git a/rust/libnbd-sys/build.rs b/rust/libnbd-sys/build.rs new file mode 100644 index 0000000..46a39b7 --- /dev/null +++ b/rust/libnbd-sys/build.rs @@ -0,0 +1,26 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +use std::fs; + +fn main() { + let libnbd_version = fs::read_to_string("libnbd_version").unwrap(); + pkg_config::Config::new() + .atleast_version(libnbd_version.trim()) + .probe("libnbd") + .unwrap(); +} diff --git a/rust/libnbd-sys/src/lib.rs b/rust/libnbd-sys/src/lib.rs new file mode 100644 index 0000000..3669ab2 --- /dev/null +++ b/rust/libnbd-sys/src/lib.rs @@ -0,0 +1,19 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +mod generated; +pub use generated::*; diff --git a/rust/run-tests.sh.in b/rust/run-tests.sh.in new file mode 100755 index 0000000..f4d220c --- /dev/null +++ b/rust/run-tests.sh.in @@ -0,0 +1,24 @@ +#!/bin/bash - +# nbd client library in userspace +# Copyright Red Hat +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library 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 +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +. ../tests/functions.sh + +set -e +set -x + +@CARGO@ test -- --nocapture diff --git a/rust/src/error.rs b/rust/src/error.rs new file mode 100644 index 0000000..631d731 --- /dev/null +++ b/rust/src/error.rs @@ -0,0 +1,157 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +use crate::sys; +use errno::Errno; +use std::ffi::{CStr, NulError}; +use std::io; + +/// A general error type for libnbd. +#[derive(Debug, thiserror::Error)] +pub enum Error { + /// Non fatal errors used when a command failed but the handle is not dead. + /// + /// If such an error is returned, it may still makes sense to call further + /// commands on the handle. + #[error(transparent)] + Recoverable(ErrorKind), + /// A fatal error. After such an error, the handle is dead and there is no + /// point in issuing further commands. + #[error("Fatal: NBD handle is dead: {0}")] + Fatal(FatalErrorKind), +} + +/// An error kind for a Libnbd related error. +#[derive(Debug, thiserror::Error)] +pub enum ErrorKind { + #[error("Errno: {errno}: {description}")] + WithErrno { errno: Errno, description: String }, + #[error("{description}")] + WithoutErrno { description: String }, + #[error(transparent)] + Errno(#[from] Errno), +} + +/// The kind of a fatal error. +#[derive(Debug, thiserror::Error)] +pub enum FatalErrorKind { + /// A Libnbd related error. + #[error(transparent)] + Libnbd(#[from] ErrorKind), + /// Some other io error. + #[error(transparent)] + Io(#[from] io::Error), +} + +pub type Result<T, E = Error> = std::result::Result<T, E>; + +impl ErrorKind { + /// Retrieve the last error from libnbd in the current thread. + pub(crate) unsafe fn get_error() -> Self { + let description = CStr::from_ptr(sys::nbd_get_error()) + .to_string_lossy() + .to_string(); + match sys::nbd_get_errno() { + 0 => Self::WithoutErrno { description }, + e => Self::WithErrno { + description, + errno: Errno(e), + }, + } + } + + /// Create an error from an errno value without any additional description. + pub fn from_errno(val: i32) -> Self { + Self::Errno(Errno(val)) + } + + /// Get the errno value if any. + pub fn errno(&self) -> Option<i32> { + match self { + Self::WithErrno { + errno: Errno(x), .. + } + | Self::Errno(Errno(x)) => Some(*x), + Self::WithoutErrno { .. } => None, + } + } +} + +impl Error { + /// Retrieve the last error from libnbd in the current thread and check if + /// the handle is dead to determine if the error is fatal or not. + pub(crate) unsafe fn get_error(handle: *mut sys::nbd_handle) -> Self { + let kind = ErrorKind::get_error(); + if sys::nbd_aio_is_dead(handle) != 0 { + Self::Fatal(FatalErrorKind::Libnbd(kind)) + } else { + Self::Recoverable(kind) + } + } + + /// Get the errno value if any. + pub fn errno(&self) -> Option<i32> { + match self { + Self::Recoverable(e) | Self::Fatal(FatalErrorKind::Libnbd(e)) => { + e.errno() + } + Self::Fatal(FatalErrorKind::Io(e)) => e.raw_os_error(), + } + } + + /// Check if this is a fatal error. + pub fn is_fatal(&self) -> bool { + match self { + Self::Fatal(_) => true, + Self::Recoverable(_) => false, + } + } + + /// Check if this is a recoverable error. + pub fn is_recoverable(&self) -> bool { + match self { + Self::Recoverable(_) => true, + Self::Fatal(_) => false, + } + } + + /// Turn this error to a [FatalErrorKind]. + pub fn to_fatal(self) -> FatalErrorKind { + match self { + Self::Fatal(e) => e, + Self::Recoverable(e) => FatalErrorKind::Libnbd(e), + } + } +} + +impl From<io::Error> for Error { + fn from(err: io::Error) -> Self { + Self::Fatal(err.into()) + } +} + +impl From<String> for Error { + fn from(description: String) -> Self { + Self::Recoverable(ErrorKind::WithoutErrno { description }) + } +} + +impl From<NulError> for Error { + fn from(e: NulError) -> Self { + e.to_string().into() + } +} diff --git a/rust/src/handle.rs b/rust/src/handle.rs new file mode 100644 index 0000000..eecc593 --- /dev/null +++ b/rust/src/handle.rs @@ -0,0 +1,65 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +use crate::sys; +use crate::{Error, ErrorKind, Result}; + +/// An NBD client handle. +#[derive(Debug)] +pub struct Handle { + /// A pointer to the raw handle. + pub(crate) handle: *mut sys::nbd_handle, +} + +impl Handle { + pub fn new() -> Result<Self> { + let handle = unsafe { sys::nbd_create() }; + if handle.is_null() { + Err(unsafe { Error::Fatal(ErrorKind::get_error().into()) }) + } else { + #[allow(unused_mut)] + let mut nbd = Handle { handle }; + #[cfg(feature = "log")] + { + nbd.set_debug_callback(|func_name, msg| { + log::debug!( + target: String::from_utf8_lossy(func_name).as_ref(), + "{}", + String::from_utf8_lossy(msg) + ); + 0 + })?; + nbd.set_debug(true)?; + } + Ok(nbd) + } + } + + /// Get the underlying C pointer to the handle. + pub(crate) fn raw_handle(&self) -> *mut sys::nbd_handle { + self.handle + } +} + +impl Drop for Handle { + fn drop(&mut self) { + unsafe { sys::nbd_close(self.handle) } + } +} + +unsafe impl Send for Handle {} +unsafe impl Sync for Handle {} diff --git a/rust/src/lib.rs b/rust/src/lib.rs new file mode 100644 index 0000000..a6f3131 --- /dev/null +++ b/rust/src/lib.rs @@ -0,0 +1,28 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +#![deny(warnings)] + +mod bindings; +mod error; +mod handle; +pub mod types; +mod utils; +pub use bindings::*; +pub use error::{Error, ErrorKind, FatalErrorKind, Result}; +pub use handle::Handle; +pub(crate) use libnbd_sys as sys; diff --git a/rust/src/types.rs b/rust/src/types.rs new file mode 100644 index 0000000..eb2df06 --- /dev/null +++ b/rust/src/types.rs @@ -0,0 +1,18 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +pub struct Cookie(pub(crate) u64); diff --git a/rust/src/utils.rs b/rust/src/utils.rs new file mode 100644 index 0000000..b8200c1 --- /dev/null +++ b/rust/src/utils.rs @@ -0,0 +1,23 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +use std::ffi::c_void; + +/// Take a C pointer to some rust data of type `T` on the heap and drop it. +pub unsafe extern "C" fn drop_data<T>(data: *mut c_void) { + drop(Box::from_raw(data as *mut T)) +} diff --git a/rustfmt.toml b/rustfmt.toml new file mode 100644 index 0000000..e6250dd --- /dev/null +++ b/rustfmt.toml @@ -0,0 +1,19 @@ +# nbd client library in userspace +# Copyright Tage Johansson +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2 of the License, or (at your option) any later version. +# +# This library 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 +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +edition = "2021" +max_width = 80 diff --git a/scripts/git.orderfile b/scripts/git.orderfile index a5a5f26..9dd3d54 100644 --- a/scripts/git.orderfile +++ b/scripts/git.orderfile @@ -61,6 +61,16 @@ common/* # Language bindings. python/* ocaml/* +rust/Cargo.toml +rust/Makefile.am +rust/run-tests.sh +rust/src/error.rs +rust/src/types.rs +rust/src/utils.rs +rust/src/lib.rs +rust/src/handle.rs +rust/libnbd-sys/* +rust/tests/* # Tests. tests/* -- 2.41.0

Make it possible to run Rust tests with Valgrind with `make check-valgrind` in the rust directory. --- rust/Makefile.am | 3 +++ rust/run-tests.sh.in | 6 +++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/rust/Makefile.am b/rust/Makefile.am index 1e63724..bb2e6f0 100644 --- a/rust/Makefile.am +++ b/rust/Makefile.am @@ -89,6 +89,9 @@ TESTS_ENVIRONMENT = \ LOG_COMPILER = $(top_builddir)/run TESTS = run-tests.sh +check-valgrind: + LIBNBD_VALGRIND=1 $(MAKE) check + clean-local: $(CARGO) clean $(CARGO) clean --manifest-path cargo_test/Cargo.toml diff --git a/rust/run-tests.sh.in b/rust/run-tests.sh.in index d45b1bf..f7db344 100755 --- a/rust/run-tests.sh.in +++ b/rust/run-tests.sh.in @@ -23,4 +23,8 @@ set -x requires nbdkit --version -@CARGO@ test -- --nocapture +if [ -z "$VG" ]; then + @CARGO@ test -- --nocapture +else + @CARGO@ test --config "target.'cfg(all())'.runner = \"$VG\"" -- --nocapture +fi -- 2.41.0

On 8/4/2023 3:04 PM, Richard W.M. Jones wrote: Strange, "make check-valgrind" works without errors for me. Could it be that we have different Valgrind installations? Or else I have no idea what would be the difference. I am quite sure the answer is no. Best regards, Tage

Add two new fields, cblifetime and cbcount, to the `closure` type in generator/API.ml*. cblifetime tells if the closure may only be used for as long as the command is in flight or if the closure may be used until the handle is destructed. cbcount tells whether the closure may be called many times or just once. This information is needed in the Rust bindings for: a) Knowing if the closure trait should be FnMut or FnOnce (see <https://doc.rust-lang.org/std/ops/trait.FnOnce.html>). b) Knowing for what lifetime the closure should be valid. A closure that may be called after the function invokation has returned must live for the `'static` lietime. But static closures are inconveniant for the user since they can't effectively borrow any local data. So it is good if this restriction is relaxed when it is not needed. --- generator/API.ml | 20 ++++++++++++++++++++ generator/API.mli | 17 +++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/generator/API.ml b/generator/API.ml index 99fcb82..41a6dd1 100644 --- a/generator/API.ml +++ b/generator/API.ml @@ -77,6 +77,8 @@ and ret = and closure = { cbname : string; cbargs : cbarg list; + cblifetime : cblifetime; + cbcount : cbcount } and cbarg = | CBArrayAndLen of arg * string @@ -87,6 +89,12 @@ and cbarg = | CBString of string | CBUInt of string | CBUInt64 of string +and cblifetime = +| CBCommand +| CBHandle +and cbcount = +| CBOnce +| CBMany and enum = { enum_prefix : string; enums : (string * int) list @@ -141,20 +149,28 @@ the handle from the NBD protocol handshake." (* Closures. *) let chunk_closure = { cbname = "chunk"; + cblifetime = CBCommand; + cbcount = CBMany; cbargs = [ CBBytesIn ("subbuf", "count"); CBUInt64 "offset"; CBUInt "status"; CBMutable (Int "error") ] } let completion_closure = { cbname = "completion"; + cblifetime = CBCommand; + cbcount = CBOnce; cbargs = [ CBMutable (Int "error") ] } let debug_closure = { cbname = "debug"; + cblifetime = CBHandle; + cbcount = CBMany; cbargs = [ CBString "context"; CBString "msg" ] } let extent_closure = { cbname = "extent"; + cblifetime = CBCommand; + cbcount = CBMany; cbargs = [ CBString "metacontext"; CBUInt64 "offset"; CBArrayAndLen (UInt32 "entries", @@ -163,10 +179,14 @@ let extent_closure = { } let list_closure = { cbname = "list"; + cblifetime = CBCommand; + cbcount = CBMany; cbargs = [ CBString "name"; CBString "description" ] } let context_closure = { cbname = "context"; + cblifetime = CBCommand; + cbcount = CBMany; cbargs = [ CBString "name" ] } let all_closures = [ chunk_closure; completion_closure; diff --git a/generator/API.mli b/generator/API.mli index 361132d..ff85849 100644 --- a/generator/API.mli +++ b/generator/API.mli @@ -94,6 +94,12 @@ and ret = and closure = { cbname : string; (** name of callback function *) cbargs : cbarg list; (** all closures return int for now *) + (** An upper bound of the lifetime of the closure. Either it will be used for + as long as the command is in flight or it may be used until the handle + is destructed. *) + cblifetime : cblifetime; + (** Whether the callback may only be called once or many times. *) + cbcount : cbcount; } and cbarg = | CBArrayAndLen of arg * string (** array + number of entries *) @@ -104,6 +110,17 @@ and cbarg = | CBString of string (** like String *) | CBUInt of string (** like UInt *) | CBUInt64 of string (** like UInt64 *) +and cblifetime = +| CBCommand (** The closure may only be used until the command is retired. + (E.G., completion callback or list callback.) *) +| CBHandle (** The closure might be used until the handle is descructed. + (E.G., debug callback.) *) +and cbcount = +| CBOnce (** The closure will be used 0 or 1 time if the aio_* call returned an + error and exactly once if the call succeeded. + (E.g., completion callback.) *) +| CBMany (** The closure may be used any number of times. + (E.g., list callback.) *) and enum = { enum_prefix : string; (** prefix of each enum variant *) enums : (string * int) list (** enum names and their values in C *) -- 2.41.0

Create another handle type: AsyncHandle, which makes use of Rust's builtin asynchronous functions (see <https://doc.rust-lang.org/std/keyword.async.html>) and runs on top of the Tokio runtime (see <https://docs.rs/tokio>). For every asynchronous command, like aio_connect(), a corresponding `async` method is created on the handle. In this case it would be: async fn connect(...) -> Result<(), ...> When called, it will poll the file descriptor until the command is complete, and then return with a result. All the synchronous counterparts (like nbd_connect()) are excluded from this handle type as they are unnecessary and since they might interfear with the polling made by the Tokio runtime. For more details about how the asynchronous commands are executed, please see the comments in rust/src/async_handle.rs. --- generator/Rust.ml | 240 +++++++++++++++++++++++++++++++++++ generator/Rust.mli | 2 + generator/generator.ml | 1 + rust/Cargo.toml | 4 +- rust/Makefile.am | 2 + rust/src/async_handle.rs | 268 +++++++++++++++++++++++++++++++++++++++ rust/src/lib.rs | 8 ++ scripts/git.orderfile | 1 + 8 files changed, 525 insertions(+), 1 deletion(-) create mode 100644 rust/src/async_handle.rs diff --git a/generator/Rust.ml b/generator/Rust.ml index 052f61b..6ec6376 100644 --- a/generator/Rust.ml +++ b/generator/Rust.ml @@ -561,3 +561,243 @@ let generate_rust_bindings () = pr "impl Handle {\n"; List.iter print_rust_handle_method handle_calls; pr "}\n\n" + +(*********************************************************) +(* The rest of the file conserns the asynchronous API. *) +(* *) +(* See the comments in rust/src/async_handle.rs for more *) +(* information about how it works. *) +(*********************************************************) + +let excluded_handle_calls : NameSet.t = + NameSet.of_list + [ + "aio_get_fd"; + "aio_get_direction"; + "aio_notify_read"; + "aio_notify_write"; + "clear_debug_callback"; + "get_debug"; + "poll"; + "poll2"; + "set_debug"; + "set_debug_callback"; + ] + +(* A mapping with names as keys. *) +module NameMap = Map.Make (String) + +(* Strip "aio_" from the beginning of a string. *) +let strip_aio name : string = + if String.starts_with ~prefix:"aio_" name then + String.sub name 4 (String.length name - 4) + else failwithf "Asynchronous call %s must begin with aio_" name + +(* A map with all asynchronous handle calls. The keys are names with "aio_" + stripped, the values are a tuple with the actual name (with "aio_"), the + [call] and the [async_kind]. *) +let async_handle_calls : ((string * call) * async_kind) NameMap.t = + handle_calls + |> List.filter (fun (n, _) -> not (NameSet.mem n excluded_handle_calls)) + |> List.filter_map (fun (name, call) -> + call.async_kind + |> Option.map (fun async_kind -> + (strip_aio name, ((name, call), async_kind)))) + |> List.to_seq |> NameMap.of_seq + +(* A mapping with all synchronous (not asynchronous) handle calls. Excluded + are also all synchronous calls that has an asynchronous counterpart. So if + "foo" is the name of a handle call and an asynchronous call "aio_foo" + exists, then "foo" will not b in this map. *) +let sync_handle_calls : call NameMap.t = + handle_calls + |> List.filter (fun (n, _) -> not (NameSet.mem n excluded_handle_calls)) + |> List.filter (fun (name, _) -> + (not (NameMap.mem name async_handle_calls)) + && not + (String.starts_with ~prefix:"aio_" name + && NameMap.mem (strip_aio name) async_handle_calls)) + |> List.to_seq |> NameMap.of_seq + +(* Get the Rust type for an argument in the asynchronous API. Like + [rust_arg_type] but no static lifetime on some closures and buffers. *) +let rust_async_arg_type : arg -> string = function + | Closure { cbargs; cbcount; cblifetime } -> + let lifetime = + match cblifetime with CBCommand -> None | CBHandle -> Some "'static" + in + "impl " ^ rust_closure_trait ~lifetime cbargs cbcount + | BytesPersistIn _ -> "&[u8]" + | BytesPersistOut _ -> "&mut [u8]" + | x -> rust_arg_type x + +(* Get the Rust type for an optional argument in the asynchronous API. Like + [rust_optarg_type] but no static lifetime on some closures. *) +let rust_async_optarg_type : optarg -> string = function + | OClosure x -> sprintf "Option<%s>" (rust_async_arg_type (Closure x)) + | x -> rust_optarg_type x + +(* A string of the argument list for a method on the handle, with both + mandotory and optional arguments. *) +let rust_async_handle_call_args { args; optargs } : string = + let rust_args_names = + List.map rust_arg_name args @ List.map rust_optarg_name optargs + and rust_args_types = + List.map rust_async_arg_type args + @ List.map rust_async_optarg_type optargs + in + String.concat ", " + (List.map2 (sprintf "%s: %s") rust_args_names rust_args_types) + +(* Print the Rust function for a not asynchronous handle call. *) +let print_rust_sync_handle_call name call = + print_rust_handle_call_comment call; + pr "pub fn %s(&self, %s) -> %s\n" name + (rust_async_handle_call_args call) + (rust_ret_type call); + print_ffi_call name "self.data.handle.handle" call; + pr "\n" + +(* Print the Rust function for an asynchronous handle call with a completion + callback. (Note that "callback" might be abbreviated with "cb" in the + following code. *) +let print_rust_async_handle_call_with_completion_cb name (aio_name, call) = + (* An array of all optional arguments. Useful because we need to deel with + the index of the completion callback. *) + let optargs = Array.of_list call.optargs in + (* The index of the completion callback in [optargs] *) + let completion_cb_index = + Array.find_map + (fun (i, optarg) -> + match optarg with + | OClosure { cbname } -> + if cbname = "completion" then Some i else None + | _ -> None) + (Array.mapi (fun x y -> (x, y)) optargs) + in + let completion_cb_index = + match completion_cb_index with + | Some x -> x + | None -> + failwithf + "The handle call %s is claimed to have a completion callback among \ + its optional arguments by the async_kind field, but so does not \ + seem to be the case." + aio_name + in + let optargs_before_completion_cb = + Array.to_list (Array.sub optargs 0 completion_cb_index) + and optargs_after_completion_cb = + Array.to_list + (Array.sub optargs (completion_cb_index + 1) + (Array.length optargs - (completion_cb_index + 1))) + in + (* All optional arguments excluding the completion callback. *) + let optargs_without_completion_cb = + optargs_before_completion_cb @ optargs_after_completion_cb + in + print_rust_handle_call_comment call; + pr "pub async fn %s(&self, %s) -> SharedResult<()> {\n" name + (rust_async_handle_call_args + { call with optargs = optargs_without_completion_cb }); + pr " // A oneshot channel to notify when the call is completed.\n"; + pr " let (ret_tx, ret_rx) = oneshot::channel::<SharedResult<()>>();\n"; + pr " let (ccb_tx, mut ccb_rx) = oneshot::channel::<c_int>();\n"; + (* Completion callback: *) + pr " let %s = Some(|err: &mut i32| {\n" + (rust_optarg_name (Array.get optargs completion_cb_index)); + pr " ccb_tx.send(*err).ok();\n"; + pr " 1\n"; + pr " });\n"; + (* End of completion callback. *) + print_ffi_call aio_name "self.data.handle.handle" call; + pr "?;\n"; + pr " let mut ret_tx = Some(ret_tx);\n"; + pr " let completion_predicate = \n"; + pr " move |_handle: &Handle, res: &SharedResult<()>| {\n"; + pr " let ret = if res.as_ref().is_err_and(|e| e.is_fatal()) {\n"; + pr " res.clone()\n"; + pr " } else {\n"; + pr " let Ok(errno) = ccb_rx.try_recv() else { return false; };\n"; + pr " if errno == 0 {\n"; + pr " Ok(())\n"; + pr " } else {\n"; + pr " if let Err(e) = res {\n"; + pr " Err(e.clone())\n"; + pr " } else {\n"; + pr " Err(Arc::new("; + pr " Error::Recoverable(ErrorKind::from_errno(errno))))\n"; + pr " }\n"; + pr " }\n"; + pr " };\n"; + pr " ret_tx.take().unwrap().send(ret).ok();\n"; + pr " true\n"; + pr " };\n"; + pr " self.add_command(completion_predicate)?;\n"; + pr " ret_rx.await.unwrap()\n"; + pr "}\n\n" + +(* Print a Rust function for an asynchronous handle call which signals + completion by changing state. The predicate is a call like + "aio_is_connecting" which should get the value (like false) for the call to + be complete. *) +let print_rust_async_handle_call_changing_state name (aio_name, call) + (predicate, value) = + let value = if value then "true" else "false" in + print_rust_handle_call_comment call; + pr "pub async fn %s(&self, %s) -> SharedResult<()>\n" name + (rust_async_handle_call_args call); + pr "{\n"; + print_ffi_call aio_name "self.data.handle.handle" call; + pr "?;\n"; + pr " let (ret_tx, ret_rx) = oneshot::channel::<SharedResult<()>>();\n"; + pr " let mut ret_tx = Some(ret_tx);\n"; + pr " let completion_predicate = \n"; + pr " move |handle: &Handle, res: &SharedResult<()>| {\n"; + pr " let ret = if let Err(_) = res {\n"; + pr " res.clone()\n"; + pr " } else {\n"; + pr " if handle.%s() != %s { return false; }\n" predicate value; + pr " else { Ok(()) }\n"; + pr " };\n"; + pr " ret_tx.take().unwrap().send(ret).ok();\n"; + pr " true\n"; + pr " };\n"; + pr " self.add_command(completion_predicate)?;\n"; + pr " ret_rx.await.unwrap()\n"; + pr "}\n\n" + +(* Print an impl with all handle calls. *) +let print_rust_async_handle_impls () = + pr "impl AsyncHandle {\n"; + NameMap.iter print_rust_sync_handle_call sync_handle_calls; + NameMap.iter + (fun name (call, async_kind) -> + match async_kind with + | WithCompletionCallback -> + print_rust_async_handle_call_with_completion_cb name call + | ChangesState (predicate, value) -> + print_rust_async_handle_call_changing_state name call + (predicate, value)) + async_handle_calls; + pr "}\n\n" + +let print_rust_async_imports () = + pr "use crate::{*, types::*};\n"; + pr "use os_socketaddr::OsSocketAddr;\n"; + pr "use std::ffi::*;\n"; + pr "use std::mem;\n"; + pr "use std::net::SocketAddr;\n"; + pr "use std::os::fd::{AsRawFd, OwnedFd};\n"; + pr "use std::os::unix::prelude::*;\n"; + pr "use std::path::PathBuf;\n"; + pr "use std::ptr;\n"; + pr "use std::sync::Arc;\n"; + pr "use tokio::sync::oneshot;\n"; + pr "\n" + +let generate_rust_async_bindings () = + generate_header CStyle ~copyright:"Tage Johansson"; + pr "\n"; + print_rust_async_imports (); + print_rust_async_handle_impls () diff --git a/generator/Rust.mli b/generator/Rust.mli index 450e4ca..0960170 100644 --- a/generator/Rust.mli +++ b/generator/Rust.mli @@ -18,3 +18,5 @@ (* Print all flag-structs, enums, constants and handle calls in Rust code. *) val generate_rust_bindings : unit -> unit + +val generate_rust_async_bindings : unit -> unit diff --git a/generator/generator.ml b/generator/generator.ml index c62b0c4..237e5c5 100644 --- a/generator/generator.ml +++ b/generator/generator.ml @@ -64,3 +64,4 @@ let () = output_to ~formatter:(Some Rustfmt) "rust/libnbd-sys/src/generated.rs" RustSys.generate_rust_sys_bindings; output_to ~formatter:(Some Rustfmt) "rust/src/bindings.rs" Rust.generate_rust_bindings; + output_to ~formatter:(Some Rustfmt) "rust/src/async_bindings.rs" Rust.generate_rust_async_bindings; diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 04e371e..e076826 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -44,9 +44,11 @@ os_socketaddr = "0.2.4" thiserror = "1.0.40" log = { version = "0.4.19", optional = true } libc = "0.2.147" +tokio = { optional = true, version = "1.29.1", default-features = false, features = ["rt", "sync", "net"] } +epoll = "4.3.3" [features] -default = ["log"] +default = ["log", "tokio"] [dev-dependencies] anyhow = "1.0.72" diff --git a/rust/Makefile.am b/rust/Makefile.am index 295254d..9fbe9fe 100644 --- a/rust/Makefile.am +++ b/rust/Makefile.am @@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk generator_built = \ libnbd-sys/src/generated.rs \ + src/async_bindings.rs \ src/bindings.rs \ $(NULL) @@ -30,6 +31,7 @@ source_files = \ src/handle.rs \ src/types.rs \ src/utils.rs \ + src/async_handle.rs \ examples/connect-command.rs \ examples/get-size.rs \ examples/fetch-first-sector.rs \ diff --git a/rust/src/async_handle.rs b/rust/src/async_handle.rs new file mode 100644 index 0000000..4223b80 --- /dev/null +++ b/rust/src/async_handle.rs @@ -0,0 +1,268 @@ +// nbd client library in userspace +// Copyright Tage Johansson +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2 of the License, or (at your option) any later version. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +// This module implements an asynchronous handle working on top of the +// [Tokio](https://tokio.rs) runtime. When the handle is created, +// a "polling task" is spawned on the Tokio runtime. The purpose of that +// "polling task" is to call `aio_notify_*` when appropriate. It shares a +// reference to the handle as well as some other things with the handle in the +// [HandleData] struct. The "polling task" is sleeping when no command is in +// flight, but wakes up as soon as any command is issued. +// +// The commands are implemented as +// [`async fn`s](https://doc.rust-lang.org/std/keyword.async.html) +// in async_bindings.rs. When a new command is issued, it registers a +// completion predicate with [Handle::add_command]. That predicate takes a +// reference to the handle and should return [true] iff the command is complete. +// Whenever some work is performed in the polling task, the completion +// predicates for all pending commands are called. + +#![allow(unused_imports)] // XXX: remove this +use crate::sys; +use crate::Handle; +use crate::{Error, FatalErrorKind, Result}; +use crate::{AIO_DIRECTION_BOTH, AIO_DIRECTION_READ, AIO_DIRECTION_WRITE}; +use epoll::Events; +use std::sync::Arc; +use std::sync::Mutex; +use tokio::io::{unix::AsyncFd, Interest, Ready as IoReady}; +use tokio::sync::{broadcast, Notify}; +use tokio::task; + +/// A custom result type with a shared [crate::Error] as default error type. +pub type SharedResult<T, E = Arc<Error>> = Result<T, E>; + +/// An NBD handle using Rust's `async` functionality on top of the +/// [Tokio](https://docs.rs/tokio/) runtime. +pub struct AsyncHandle { + /// Data shared both by this struct and the polling task. + pub(crate) data: Arc<HandleData>, + + /// A task which soely purpose is to poll the NBD handle. + polling_task: tokio::task::AbortHandle, +} + +pub(crate) struct HandleData { + /// The underliing handle. + pub handle: Handle, + + /// A list of all pending commands. + /// + /// For every pending command (commands in flight), a predicate will be + /// stored in this list. Whenever some progress is made on the file + /// descriptor, the predicate is called with a reference to the handle + /// and a reference to the result of that call to `aio_notify_*`. + /// Iff the predicate returns [true], the command is considered completed + /// and removed from this list. + /// + /// If The polling task dies for some reason, this [SharedResult] will be + /// set to some error. + pub pending_commands: Mutex< + SharedResult< + Vec< + Box< + dyn FnMut(&Handle, &SharedResult<()>) -> bool + + Send + + Sync + + 'static, + >, + >, + >, + >, + + /// A notifier used by commands to notify the polling task when a new + /// asynchronous command is issued. + pub new_command: Notify, +} + +impl AsyncHandle { + pub fn new() -> Result<Self> { + let handle_data = Arc::new(HandleData { + handle: Handle::new()?, + pending_commands: Mutex::new(Ok(Vec::new())), + new_command: Notify::new(), + }); + + let handle_data_2 = handle_data.clone(); + let polling_task = task::spawn(async move { + // The polling task should never finish without an error. If the + // handle is dropped, the task is aborted so it'll not return in + // that case either. + let Err(err) = polling_task(&handle_data_2).await else { + unreachable!() + }; + let err = Arc::new(Error::Fatal(err)); + // Call the completion predicates for all pending commands with the + // error. + let mut pending_cmds = + handle_data_2.pending_commands.lock().unwrap(); + let res = Err(err); + for f in pending_cmds.as_mut().unwrap().iter_mut() { + f(&handle_data_2.handle, &res); + } + *pending_cmds = Err(res.unwrap_err()); + }) + .abort_handle(); + Ok(Self { + data: handle_data, + polling_task, + }) + } + + /// Get the underliing C pointer to the handle. + pub(crate) fn raw_handle(&self) -> *mut sys::nbd_handle { + self.data.handle.raw_handle() + } + + /// Call this method when a new command is issued. As argument is passed a + /// predicate which should return [true] iff the command is completed. + pub(crate) fn add_command( + &self, + mut completion_predicate: impl FnMut(&Handle, &SharedResult<()>) -> bool + + Send + + Sync + + 'static, + ) -> SharedResult<()> { + if !completion_predicate(&self.data.handle, &Ok(())) { + let mut pending_cmds_lock = + self.data.pending_commands.lock().unwrap(); + pending_cmds_lock + .as_mut() + .map_err(|e| e.clone())? + .push(Box::new(completion_predicate)); + self.data.new_command.notify_one(); + } + Ok(()) + } +} + +impl Drop for AsyncHandle { + fn drop(&mut self) { + self.polling_task.abort(); + } +} + +/// Get the read/write direction that the handle wants on the file descriptor. +fn get_fd_interest(handle: &Handle) -> Option<Interest> { + match handle.aio_get_direction() { + 0 => None, + AIO_DIRECTION_READ => Some(Interest::READABLE), + AIO_DIRECTION_WRITE => Some(Interest::WRITABLE), + AIO_DIRECTION_BOTH => Some(Interest::READABLE | Interest::WRITABLE), + _ => unreachable!(), + } +} + +/// A task that will run as long as the handle is alive. It will poll the +/// file descriptor when new data is availlable. +async fn polling_task(handle_data: &HandleData) -> Result<(), FatalErrorKind> { + let HandleData { + handle, + pending_commands, + new_command, + } = handle_data; + let fd = handle.aio_get_fd().map_err(Error::to_fatal)?; + // XXX: Might the file descriptor ever be changed? + let tokio_fd = AsyncFd::new(fd)?; + let epfd = epoll::create(false)?; + epoll::ctl( + epfd, + epoll::ControlOptions::EPOLL_CTL_ADD, + fd, + epoll::Event::new(Events::EPOLLIN | Events::EPOLLOUT, 42), + )?; + + // The following loop does approximately the following things: + // + // 1. Determine what Libnbd wants to do next on the file descriptor, + // (read/write/both/none), and store that in [fd_interest]. + // 2. Wait for either: + // a) That interest to be available on the file descriptor in which case: + // I. Call the correct `aio_notify_*` method. + // II. Execute step 1. + // III. Send the result of the call to `aio_notify_*` on + // [result_channel] to notify pending commands that some progress + // has been made. + // IV. Resume execution from step 2. + // b) A notification was received on [new_command] signaling that a new + // command was registered and that the intrest on the file descriptor + // might has changed. Resume execution from step 1. + loop { + let Some(fd_interest) = get_fd_interest(handle) else { + // The handle does not wait for any data of the file descriptor, + // so we wait until some command is issued. + new_command.notified().await; + continue; + }; + + if pending_commands + .lock() + .unwrap() + .as_ref() + .unwrap() + .is_empty() + { + // No command is pending so there is no point to do anything. + new_command.notified().await; + continue; + } + + // Wait for the requested interest to be available on the fd. + let mut ready_guard = tokio_fd.ready(fd_interest).await?; + let readyness = ready_guard.ready(); + let res = if readyness.is_readable() && fd_interest.is_readable() { + handle.aio_notify_read() + } else if readyness.is_writable() && fd_interest.is_writable() { + handle.aio_notify_write() + } else { + continue; + }; + let res = match res { + Ok(()) => Ok(()), + Err(e @ Error::Recoverable(_)) => Err(Arc::new(e)), + Err(Error::Fatal(e)) => return Err(e), + }; + + // Call the completion predicates of all pending commands. + let mut pending_cmds_lock = pending_commands.lock().unwrap(); + let pending_cmds = pending_cmds_lock.as_mut().unwrap(); + let mut i = 0; + while i < pending_cmds.len() { + if (pending_cmds[i])(handle, &res) { + let _ = pending_cmds.swap_remove(i); + } else { + i += 1; + } + } + drop(pending_cmds_lock); + + // Use epoll to check the current read/write availability on the fd. + // This is needed because Tokio does only support edge-triggered + // notifications but Libnbd requires level-triggered notifications. + let mut revent = epoll::Event { data: 0, events: 0 }; + // Setting timeout to 0 means that it will return immediately. + epoll::wait(epfd, 0, std::slice::from_mut(&mut revent))?; + let revents = Events::from_bits(revent.events).unwrap(); + if !revents.contains(Events::EPOLLIN) { + ready_guard.clear_ready_matching(IoReady::READABLE); + } + if !revents.contains(Events::EPOLLOUT) { + ready_guard.clear_ready_matching(IoReady::WRITABLE); + } + ready_guard.retain_ready(); + } +} diff --git a/rust/src/lib.rs b/rust/src/lib.rs index a6f3131..56316b4 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -17,11 +17,19 @@ #![deny(warnings)] +#[cfg(feature = "tokio")] +mod async_bindings; +#[cfg(feature = "tokio")] +mod async_handle; mod bindings; mod error; mod handle; pub mod types; mod utils; +#[cfg(feature = "tokio")] +pub use async_bindings::*; +#[cfg(feature = "tokio")] +pub use async_handle::{AsyncHandle, SharedResult}; pub use bindings::*; pub use error::{Error, ErrorKind, FatalErrorKind, Result}; pub use handle::Handle; diff --git a/scripts/git.orderfile b/scripts/git.orderfile index b988d87..60ec56d 100644 --- a/scripts/git.orderfile +++ b/scripts/git.orderfile @@ -69,6 +69,7 @@ rust/src/types.rs rust/src/utils.rs rust/src/lib.rs rust/src/handle.rs +rust/src/async_handle.rs rust/libnbd-sys/* rust/examples/* rust/tests/* -- 2.41.0

All handle calls which has the modifies_fd flag set to true will be excluded from AsyncHandle (the asynchronous handle in the rust bindings). This is a better approach then listing all calls that should be excluded in Rust.ml explicetly. --- generator/Rust.ml | 60 +++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 33 deletions(-) diff --git a/generator/Rust.ml b/generator/Rust.ml index 6ec6376..c08920d 100644 --- a/generator/Rust.ml +++ b/generator/Rust.ml @@ -571,18 +571,17 @@ let generate_rust_bindings () = let excluded_handle_calls : NameSet.t = NameSet.of_list - [ - "aio_get_fd"; - "aio_get_direction"; - "aio_notify_read"; - "aio_notify_write"; - "clear_debug_callback"; - "get_debug"; - "poll"; - "poll2"; - "set_debug"; - "set_debug_callback"; - ] + @@ [ + "aio_get_fd"; + "aio_get_direction"; + "clear_debug_callback"; + "get_debug"; + "set_debug"; + "set_debug_callback"; + ] + @ (handle_calls + |> List.filter (fun (_, { modifies_fd }) -> modifies_fd) + |> List.map (fun (name, _) -> name)) (* A mapping with names as keys. *) module NameMap = Map.Make (String) @@ -593,16 +592,16 @@ let strip_aio name : string = String.sub name 4 (String.length name - 4) else failwithf "Asynchronous call %s must begin with aio_" name -(* A map with all asynchronous handle calls. The keys are names with "aio_" - stripped, the values are a tuple with the actual name (with "aio_"), the - [call] and the [async_kind]. *) +(* A map with all asynchronous handle calls. The keys are names, the values + are tuples of: the name with "aio_" stripped, the [call] and the + [async_kind]. *) let async_handle_calls : ((string * call) * async_kind) NameMap.t = handle_calls |> List.filter (fun (n, _) -> not (NameSet.mem n excluded_handle_calls)) |> List.filter_map (fun (name, call) -> call.async_kind |> Option.map (fun async_kind -> - (strip_aio name, ((name, call), async_kind)))) + (name, ((strip_aio name, call), async_kind)))) |> List.to_seq |> NameMap.of_seq (* A mapping with all synchronous (not asynchronous) handle calls. Excluded @@ -612,11 +611,7 @@ let async_handle_calls : ((string * call) * async_kind) NameMap.t = let sync_handle_calls : call NameMap.t = handle_calls |> List.filter (fun (n, _) -> not (NameSet.mem n excluded_handle_calls)) - |> List.filter (fun (name, _) -> - (not (NameMap.mem name async_handle_calls)) - && not - (String.starts_with ~prefix:"aio_" name - && NameMap.mem (strip_aio name) async_handle_calls)) + |> List.filter (fun (n, _) -> not (NameMap.mem n async_handle_calls)) |> List.to_seq |> NameMap.of_seq (* Get the Rust type for an argument in the asynchronous API. Like @@ -661,7 +656,7 @@ let print_rust_sync_handle_call name call = (* Print the Rust function for an asynchronous handle call with a completion callback. (Note that "callback" might be abbreviated with "cb" in the following code. *) -let print_rust_async_handle_call_with_completion_cb name (aio_name, call) = +let print_rust_async_handle_call_with_completion_cb aio_name (name, call) = (* An array of all optional arguments. Useful because we need to deel with the index of the completion callback. *) let optargs = Array.of_list call.optargs in @@ -741,7 +736,7 @@ let print_rust_async_handle_call_with_completion_cb name (aio_name, call) = completion by changing state. The predicate is a call like "aio_is_connecting" which should get the value (like false) for the call to be complete. *) -let print_rust_async_handle_call_changing_state name (aio_name, call) +let print_rust_async_handle_call_changing_state aio_name (name, call) (predicate, value) = let value = if value then "true" else "false" in print_rust_handle_call_comment call; @@ -770,16 +765,15 @@ let print_rust_async_handle_call_changing_state name (aio_name, call) (* Print an impl with all handle calls. *) let print_rust_async_handle_impls () = pr "impl AsyncHandle {\n"; - NameMap.iter print_rust_sync_handle_call sync_handle_calls; - NameMap.iter - (fun name (call, async_kind) -> - match async_kind with - | WithCompletionCallback -> - print_rust_async_handle_call_with_completion_cb name call - | ChangesState (predicate, value) -> - print_rust_async_handle_call_changing_state name call - (predicate, value)) - async_handle_calls; + sync_handle_calls |> NameMap.iter print_rust_sync_handle_call; + async_handle_calls + |> NameMap.iter (fun name (call, async_kind) -> + match async_kind with + | WithCompletionCallback -> + print_rust_async_handle_call_with_completion_cb name call + | ChangesState (predicate, value) -> + print_rust_async_handle_call_changing_state name call + (predicate, value)); pr "}\n\n" let print_rust_async_imports () = -- 2.41.0

This patch adds an example using the asynchronous Rust bindings. --- rust/Cargo.toml | 1 + rust/examples/concurrent-read-write.rs | 135 +++++++++++++++++++++++++ rust/run-tests.sh.in | 2 + 3 files changed, 138 insertions(+) create mode 100644 rust/examples/concurrent-read-write.rs diff --git a/rust/Cargo.toml b/rust/Cargo.toml index d001248..4332783 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -54,5 +54,6 @@ default = ["log", "tokio"] anyhow = "1.0.72" once_cell = "1.18.0" pretty-hex = "0.3.0" +rand = { version = "0.8.5", default-features = false, features = ["small_rng", "min_const_gen"] } tempfile = "3.6.0" tokio = { version = "1.29.1", default-features = false, features = ["rt-multi-thread", "macros"] } diff --git a/rust/examples/concurrent-read-write.rs b/rust/examples/concurrent-read-write.rs new file mode 100644 index 0000000..a1c3e8a --- /dev/null +++ b/rust/examples/concurrent-read-write.rs @@ -0,0 +1,135 @@ +//! Example usage with nbdkit: +//! +//! nbdkit -U - memory 100M \ +//! --run 'cargo run --example concurrent-read-write -- $unixsocket' +//! +//! This will read and write randomly over the first megabyte of the +//! plugin using multi-conn, multiple threads and multiple requests in +//! flight on each thread. + +#![deny(warnings)] +use rand::prelude::*; +use std::env; +use std::path::PathBuf; +use std::sync::Arc; +use tokio::task::JoinSet; + +/// Number of simultaneous connections to the NBD server. +/// +/// Note that some servers only support a limited number of +/// simultaneous connections, and/or have a configurable thread pool +/// internally, and if you exceed those limits then something will break. +const NR_MULTI_CONN: usize = 8; + +/// Number of commands that can be "in flight" at the same time on each +/// connection. (Therefore the total number of requests in flight may +/// be up to NR_MULTI_CONN * MAX_IN_FLIGHT). +const MAX_IN_FLIGHT: usize = 16; + +/// The size of large reads and writes, must be > 512. +const BUFFER_SIZE: usize = 1024; + +/// Number of commands we issue (per [task][tokio::task]). +const NR_CYCLES: usize = 32; + +/// Statistics gathered during the run. +#[derive(Debug, Default)] +struct Stats { + /// The total number of requests made. + requests: usize, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let args = env::args_os().collect::<Vec<_>>(); + if args.len() != 2 { + anyhow::bail!("Usage: {:?} socket", args[0]); + } + let socket = &args[1]; + + // We begin by making a connection to the server to get the export size + // and ensure that it supports multiple connections and is writable. + let nbd = libnbd::Handle::new()?; + nbd.connect_unix(&socket)?; + let export_size = nbd.get_size()?; + anyhow::ensure!( + (BUFFER_SIZE as u64) < export_size, + "export is {export_size}B, must be larger than {BUFFER_SIZE}B" + ); + anyhow::ensure!( + !nbd.is_read_only()?, + "error: this NBD export is read-only" + ); + anyhow::ensure!( + nbd.can_multi_conn()?, + "error: this NBD export does not support multi-conn" + ); + drop(nbd); // Close the connection. + + // Start the worker tasks, one per connection. + let mut tasks = JoinSet::new(); + for i in 0..NR_MULTI_CONN { + tasks.spawn(run_thread(i, socket.clone().into(), export_size)); + } + + // Wait for the tasks to complete. + let mut stats = Stats::default(); + while !tasks.is_empty() { + let this_stats = tasks.join_next().await.unwrap().unwrap()?; + stats.requests += this_stats.requests; + } + + // Make sure the number of requests that were required matches what + // we expect. + assert_eq!(stats.requests, NR_MULTI_CONN * NR_CYCLES); + + Ok(()) +} + +async fn run_thread( + task_idx: usize, + socket: PathBuf, + export_size: u64, +) -> anyhow::Result<Stats> { + // Start a new connection to the server. + // We shall spawn many commands concurrently on different tasks and those + // futures must be `'static`, hence we wrap the handle in an [Arc]. + let nbd = Arc::new(libnbd::AsyncHandle::new()?); + nbd.connect_unix(socket).await?; + + let mut rng = SmallRng::seed_from_u64(44 as u64); + + // Issue commands. + let mut stats = Stats::default(); + let mut join_set = JoinSet::new(); + //tokio::time::sleep(std::time::Duration::from_secs(1)).await; + while stats.requests < NR_CYCLES || !join_set.is_empty() { + while stats.requests < NR_CYCLES && join_set.len() < MAX_IN_FLIGHT { + // If we want to issue another request, do so. Note that we reuse + // the same buffer for multiple in-flight requests. It doesn't + // matter here because we're just trying to write random stuff, + // but that would be Very Bad in a real application. + // Simulate a mix of large and small requests. + let size = if rng.gen() { BUFFER_SIZE } else { 512 }; + let offset = rng.gen_range(0..export_size - size as u64); + + let mut buf = [0u8; BUFFER_SIZE]; + let nbd = nbd.clone(); + if rng.gen() { + join_set.spawn(async move { + nbd.pread(&mut buf, offset, None).await + }); + } else { + // Fill the buf with random data. + rng.fill(&mut buf); + join_set + .spawn(async move { nbd.pwrite(&buf, offset, None).await }); + } + stats.requests += 1; + } + join_set.join_next().await.unwrap().unwrap()?; + } + + if task_idx == 0 {} + Ok(stats) +} diff --git a/rust/run-tests.sh.in b/rust/run-tests.sh.in index 138a1fa..24858dd 100755 --- a/rust/run-tests.sh.in +++ b/rust/run-tests.sh.in @@ -32,6 +32,8 @@ if [ -z "$VG" ]; then --run '@CARGO@ run --example get-size -- $unixsocket' nbdkit -U - floppy . \ --run '@CARGO@ run --example fetch-first-sector -- $unixsocket' + nbdkit -U - memory 10M \ + --run '@CARGO@ run --example concurrent-read-write -- $unixsocket' else @CARGO@ test --config "target.'cfg(all())'.runner = \"$VG\"" -- --nocapture fi -- 2.41.0