Merge branch 'main' of https://github.com/jhg/opaque-pointer-rs

Author: jhg

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: jhg

.github/workflows/test.yml

@@ -27,13 +27,15 @@ env:
 
 jobs:
   test:
+    needs: lint
     strategy:
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
         rust: [ stable, beta ]
         features: [ 'std', 'alloc', 'std,lender', 'alloc,lender' ]
     runs-on: ${{ matrix.os }}
     timeout-minutes: 5
+    continue-on-error: true
     if: github.event_name != 'schedule' && github.event_name != 'workflow_dispatch' && !endsWith(github.ref, '-nightly') && !endsWith(github.head_ref, '-nightly')
     steps:
     - uses: actions/checkout@v2
@@ -67,13 +69,15 @@ jobs:
     - name: Run fmt
       run: cargo fmt --verbose --all -- --check
   nightly-test:
+    needs: nightly-lint
     strategy:
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
         rust: [ nightly ]
         features: [ 'std', 'alloc', 'std,lender', 'alloc,lender' ]
     runs-on: ${{ matrix.os }}
     timeout-minutes: 5
+    continue-on-error: true
     steps:
     - uses: actions/checkout@v2
     - uses: actions-rs/toolchain@v1

.idea/.gitignore

@@ -1,28 +1,37 @@
 [package]
 name = "opaque-pointer"
-version = "0.8.8"
+version = "0.9.0"
 description = "Generic functions to work with opaque pointers when use FFI to expose Rust structs"
-authors = ["Jesus Hernandez <[email protected]>"]
+authors = [
+    "Jesus Hernandez <[email protected]>",
+    "Dylan DPC",
+]
 license = "Unlicense"
-keywords = ["pointer", "opaque", "pointers", "cbindgen", "ffi"]
+keywords = ["opaque", "pointers", "cbindgen", "ffi", "no_std"]
 categories = ["development-tools::ffi", "no-std"]
 edition = "2021"
 readme = "README.md"
 repository = "https://github.com/jhg/opaque-pointer-rs/"
-exclude = [".github/**", ".vscode/**"]
+exclude = [
+    ".github/**",
+    ".vscode/**",
+    ".idea/**",
+    "tests/**", # To reduce the package size, as tests are not needed to use it.
+]
+rust-version = "1.57.0" # For HashSet::try_reserve
 
 [features]
-default = ["std"]
+default = ["std", "lender"]
 std = []
-# If you does not use std then you need alloc feature
+lender = ["lazy_static"]
+# If you do not use std then you need alloc feature
 alloc = []
 # Allow to use some FFI for C types
 c-types = ["std"]
-lender = ["lazy_static"]
 
 [dependencies]
 log = "0.4"
-lazy_static = { version = "^1", optional = true }
+lazy_static = { version = "1.4", optional = true }
 
 [package.metadata.docs.rs]
 features = ["std", "lender"]

.idea/modules.xml

@@ -1,26 +1,22 @@
-# opaque-pointer-rs
+# Opaque Pointer for seamless Rust FFI
 
-Generic functions to work with opaque pointers when use FFI to expose Rust structs
+Harnessing generics with opaque pointers for seamless Rust FFI interoperability with C and C++
 
 [![Crates.io](https://img.shields.io/crates/v/opaque-pointer)](https://crates.io/crates/opaque-pointer)
 [![Crates.io](https://img.shields.io/crates/l/opaque-pointer)](https://unlicense.org/)
 [![Crates.io](https://img.shields.io/crates/d/opaque-pointer)](https://crates.io/crates/opaque-pointer)
 
-## Basic usage
+## Overview
 
-With this crate you can manage raw pointers easily to expose `structs` that will be
- use as opaque pointers from C or C++ calling to Rust functions to use it. This
- can be used with [cbindgen](https://crates.io/crates/cbindgen) crate with option `parse.parse_deps = true`
- for it will generate opaque C/C++ `structs` to use pointers in the arguments.
+Simplify raw pointer management to expose Rust structs as opaque pointers, seamlessly enabling interaction between Rust and C/C++ functions.
+This crate facilitates creating opaque C/C++ structs for use with arguments, generated by [cbindgen](https://crates.io/crates/cbindgen) with `parse.parse_deps = true`.
 
-You can find more information about using Rust from other languages in
- [The Rust FFI Omnibus objects section](http://jakegoulding.com/rust-ffi-omnibus/objects/)
- of [Jake Goulding](https://github.com/shepmaster).
+For comprehensive insights into Rust's interoperability with other languages, explore [The Rust FFI Omnibus objects section](http://jakegoulding.com/rust-ffi-omnibus/objects/) by [Jake Goulding](https://github.com/shepmaster).
 
 ## Lender feature
 
-If you activate the feature `lender` the functions like `own_back<T>()` will check if the pointer is valid.
-It means, the function result will be a error if the pointer was not returned by `raw<T>()`.
+By activating the `lender` feature, functions like `own_back<T>()` validate the pointer, ensuring its validity.
+It means, be returned by `raw<T>()`.
 
 ## Examples
 
@@ -38,13 +34,14 @@ impl Counter {
 /// Ownership will NOT control the heap-allocated memory until own it back.
 #[no_mangle]
 pub extern fn counter_new(value: u8) -> *mut Counter {
-    return opaque_pointer::raw(Counter::new());
+    return opaque_pointer::raw(Counter::new())
+            .expect("Error trying to lend a pointer");
 }
 
 /// Drop (free memory of) Rust's Counter object as usually.
 #[no_mangle]
 pub extern fn counter_free(counter: *mut Counter) {
-    unsafe { opaque_pointer::free(counter) };
+    unsafe { opaque_pointer::own_back(counter) };
 }
 
 #[no_mangle]

.idea/opaque-pointer-rs.iml

@@ -7,7 +7,7 @@
 use std::ffi::CStr;
 use std::os::raw::c_char;
 
-use super::validate_pointer_is_not_null;
+use crate::validation::not_null_pointer;
 
 use crate::error::PointerError;
 
@@ -25,7 +25,7 @@ use crate::error::PointerError;
 pub unsafe fn ref_str<'a>(string: *const c_char) -> Result<&'a str, PointerError> {
     // ATTENTION! 'a lifetime is required, does NOT REMOVE it
     // see commit 5a03be91d2da8909986db7c54650f3a7863a91ff fixing 3a1d15f33e8e418ef6bee2b7b9e096780bd2c8ac
-    validate_pointer_is_not_null(string)?;
+    not_null_pointer(string)?;
     // CAUTION: this is unsafe
     let string = CStr::from_ptr(string);
     return Ok(string.to_str()?);

.idea/vcs.xml

@@ -1,6 +1,10 @@
 //! Opaque pointers errors.
 
+#[cfg(all(feature = "alloc", not(feature = "std")))]
+use alloc::collections::TryReserveError;
 use core::str::Utf8Error;
+#[cfg(feature = "std")]
+use std::collections::TryReserveError;
 
 /// Errors that can be detected by the functions of this crate.
 ///
@@ -14,19 +18,29 @@ pub enum PointerError {
     Invalid,
     /// Trying to convert to `&str` a C string which content is not valid UTF-8.
     Utf8Error(Utf8Error),
+    /// Trying to alloc memory, see [`alloc::collections::TryReserveError`].
+    #[cfg(any(feature = "alloc", feature = "std"))]
+    TryReserveError(TryReserveError),
 }
 
 impl core::fmt::Display for PointerError {
     fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
-        match *self {
+        match self {
             Self::Null => {
                 write!(f, "dereference a null pointer will produce a crash")
             }
             Self::Invalid => {
                 write!(f, "dereference a unknown pointer could produce a crash")
             }
-            Self::Utf8Error(..) => {
-                write!(f, "the provided C string is not a valid UTF-8 string")
+            Self::Utf8Error(error) => {
+                write!(
+                    f,
+                    "the provided C string is not a valid UTF-8 string: {error}"
+                )
+            }
+            #[cfg(any(feature = "alloc", feature = "std"))]
+            Self::TryReserveError(error) => {
+                write!(f, "can not alloc memory of internal usage: {error}")
             }
         }
     }
@@ -35,15 +49,23 @@ impl core::fmt::Display for PointerError {
 #[cfg(feature = "std")] // Waiting for https://github.com/rust-lang/rust/issues/103765
 impl std::error::Error for PointerError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
-        match *self {
+        match self {
             Self::Null | Self::Invalid => None,
-            Self::Utf8Error(ref e) => Some(e),
+            Self::Utf8Error(error) => Some(error),
+            Self::TryReserveError(error) => Some(error),
         }
     }
 }
 
 impl From<Utf8Error> for PointerError {
-    fn from(err: Utf8Error) -> Self {
-        Self::Utf8Error(err)
+    fn from(error: Utf8Error) -> Self {
+        Self::Utf8Error(error)
+    }
+}
+
+#[cfg(any(feature = "alloc", feature = "std"))]
+impl From<TryReserveError> for PointerError {
+    fn from(error: TryReserveError) -> Self {
+        Self::TryReserveError(error)
     }
 }