From bcb5348efbd98bb8192522dcd8afe82d5911b2a0 Mon Sep 17 00:00:00 2001 From: Simonas Kazlauskas Date: Sun, 5 Apr 2020 16:33:26 +0300 Subject: [PATCH] Improve documentation --- Cargo.toml | 2 +- src/changelog.rs | 26 ++++++++++++++++++++------ src/lib.rs | 9 +++++---- src/os/unix/mod.rs | 10 +++++++--- src/os/windows/mod.rs | 5 +++-- 5 files changed, 36 insertions(+), 16 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index fd81c61..9b39131 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "libloading" -version = "0.5.2" +version = "0.6.0" authors = ["Simonas Kazlauskas "] build = "build.rs" description = "A safer binding to platform’s dynamic library loading utilities" diff --git a/src/changelog.rs b/src/changelog.rs index 9e2e34a..b2fc613 100644 --- a/src/changelog.rs +++ b/src/changelog.rs @@ -1,12 +1,26 @@ //! Project changelog -/// Release NEXT (2020-04-??) +/// Release 0.6.0 (2020-04-0?) /// -/// * Removed dependency on the C compiler to build this library on unix-like platforms. We used to -/// utilize it to work-around the very unlikely possibility of the target having thread-unsafe -/// `dlerror` function, but the effect of the work-around was very opportunistic. We deemed the -/// cost of the work-around to be higher than the benefit of it. -pub mod rNEXT {} +/// * Introduced a new method [`os::unix::Library::get_singlethreaded`]; +/// * Added (untested) support for building when targetting Redox and Fuchsia; +/// +/// ## Breaking changes +/// +/// * Removed the dependency on the C compiler to build this library on UNIX-like platforms. +/// `libloading` used to utilize a snippet written in C to work-around the unlikely possibility +/// of the target having a thread-unsafe implementation of the `dlerror` function. The effect of +/// the work-around was very opportunistic: it would not work if the function was called by +/// forgoing `libloading`. +/// +/// Starting with 0.6.0, [`Library::get`] on platforms where `dlerror` is not MT-safe (such as +/// FreeBSD, DragonflyBSD or NetBSD) will unconditionally return an error when the underlying +/// `dlsym` returns a null pointer. For the use-cases where loading null pointers is necessary +/// consider using [`os::unix::Library::get_singlethreaded`] instead. +/// +/// [`Library::get`]: crate::Library::get +/// [`os::unix::Library::get_singlethreaded`]: crate::os::unix::Library::get_singlethreaded +pub mod r0_6_0 {} /// Release 0.5.2 (2019-07-07) diff --git a/src/lib.rs b/src/lib.rs index c73ff49..b63fb97 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -137,10 +137,11 @@ impl Library { /// some sort of lazy initialization scheme, which makes loading TLS variables this way /// impossible. Using a TLS variable loaded this way on OS X is undefined behaviour. /// - /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe, this - /// function will return an error if this function was to return `Ok` with a null `Symbol` - /// otherwise. As a work-around consider using the platform-specific - /// [`os::unix::Library::get_singlethreaded`] call. + /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe (such + /// as FreeBSD), this function will unconditionally return an error the underlying `dlsym` call + /// returns a null pointer. There are rare situations where `dlsym` returns a genuine null + /// pointer without it being an error. If loading a null pointer is something you care about, + /// consider using the [`os::unix::Library::get_singlethreaded`] call. /// /// ## Examples /// diff --git a/src/os/unix/mod.rs b/src/os/unix/mod.rs index 01f2031..e14cdbf 100644 --- a/src/os/unix/mod.rs +++ b/src/os/unix/mod.rs @@ -189,14 +189,18 @@ impl Library { /// ensure that the loaded symbol is in fact a `T`. Using a value with a wrong type has no /// definied behaviour. /// + /// + /// /// ## Platform-specific behaviour /// /// OS X uses some sort of lazy initialization scheme, which makes loading TLS variables /// impossible. Using a TLS variable loaded this way on OS X is undefined behaviour. /// - /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe, this - /// function will return an error if this function was to return `Ok` with a null `Symbol` - /// on other platforms. As a work-around consider using the [`Self::get_singlethreaded`] call. + /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe (such + /// as FreeBSD), this function will unconditionally return an error the underlying `dlsym` call + /// returns a null pointer. There are rare situations where `dlsym` returns a genuine null + /// pointer without it being an error. If loading a null pointer is something you care about, + /// consider using the [`Library::get_singlethreaded`] call. #[inline(always)] pub unsafe fn get(&self, symbol: &[u8]) -> ::Result> { #[cfg(mtsafe_dlerror)] diff --git a/src/os/windows/mod.rs b/src/os/windows/mod.rs index 8157eab..6ea272c 100644 --- a/src/os/windows/mod.rs +++ b/src/os/windows/mod.rs @@ -68,8 +68,9 @@ impl Library { /// /// ## Unsafety /// - /// Pointer to a value of arbitrary type is returned. Using a value with wrong type is - /// undefined. + /// This function does not validate the type `T`. It is up to the user of this function to + /// ensure that the loaded symbol is in fact a `T`. Using a value with a wrong type has no + /// definied behaviour. pub unsafe fn get(&self, symbol: &[u8]) -> ::Result> { ensure_compatible_types::(); let symbol = try!(cstr_cow_from_bytes(symbol));