Experimental use of constructor functions to call init (#334)

* Experimental use of constructor functions to call init

As mentioned in #333, this is a potentially helpful addition that ensures that curl is initialized on the main thread by using constructor functions that get called by the OS before the current program's `main` is called.

This has the advantage that, assuming you are on one of the supported platforms, `init()` will be called safely, correctly, and automatically without concerning the user about the gotchas.

This does have some disadvantages:

- Constructor functions are always invoked, which means that simply including curl can slow down the startup of a user's program even if curl is only conditionally used, or used later in program execution.
- On platforms without a constructor implementation, the user still needs to initialize curl on the main thread. All the common platforms are covered though, so maybe this is a niche scenario.

There's no additional runtime cost to this implementation except on platforms without a constructor, where we do an extra atomic swap that isn't necessary. This is probably fixable with additional conditional compilation.

* Micro-optimization

Ensure subsequent init calls are compiled down to a single atomic compare-and-swap.

* Consolidate ELF attribute

* Reducing to just a Once is acceptable

Since it is not possible for the `Once` to have contention in a constructor, it is safe to use it. (Under contention, `Once` requires `std::thread` machinery to work, which is not yet available before `main`.)

Also update documentation on initialization.

Author: sagebind

src/lib.rs

@@ -46,6 +46,12 @@
 //! There is a large number of releases for libcurl, all with different sets of
 //! capabilities. Robust programs may wish to inspect `Version::get()` to test
 //! what features are implemented in the linked build of libcurl at runtime.
+//!
+//! # Initialization
+//!
+//! The underlying libcurl library must be initialized before use and has
+//! certain requirements on how this is done. Check the documentation for
+//! [`init`] for more details.
 
 #![deny(missing_docs, missing_debug_implementations)]
 #![doc(html_root_url = "https://docs.rs/curl/0.4")]
@@ -78,34 +84,63 @@ mod panic;
 
 /// Initializes the underlying libcurl library.
 ///
-/// It's not required to call this before the library is used, but it's
-/// recommended to do so as soon as the program starts.
+/// The underlying libcurl library must be initialized before use, and must be
+/// done so on the main thread before any other threads are created by the
+/// program. This crate will do this for you automatically in the following
+/// scenarios:
+///
+/// - Creating a new [`Easy`][easy::Easy] or [`Multi`][multi::Multi] handle
+/// - At program startup on Windows, macOS, Linux, Android, or FreeBSD systems
+///
+/// This should be sufficient for most applications and scenarios, but in any
+/// other case, it is strongly recommended that you call this function manually
+/// as soon as your program starts.
+///
+/// Calling this function more than once is harmless and has no effect.
+#[inline]
 pub fn init() {
+    /// Used to prevent concurrent or duplicate initialization.
     static INIT: Once = Once::new();
-    INIT.call_once(|| {
-        platform_init();
-        unsafe {
-            assert_eq!(curl_sys::curl_global_init(curl_sys::CURL_GLOBAL_ALL), 0);
-        }
-
-        // Note that we explicitly don't schedule a call to
-        // `curl_global_cleanup`. The documentation for that function says
-        //
-        // > You must not call it when any other thread in the program (i.e. a
-        // > thread sharing the same memory) is running. This doesn't just mean
-        // > no other thread that is using libcurl.
-        //
-        // We can't ever be sure of that, so unfortunately we can't call the
-        // function.
-    });
-
-    #[cfg(need_openssl_init)]
-    fn platform_init() {
-        openssl_sys::init();
+
+    /// An exported constructor function. On supported platforms, this will be
+    /// invoked automatically before the program's `main` is called.
+    #[cfg_attr(
+        any(target_os = "linux", target_os = "freebsd", target_os = "android"),
+        link_section = ".init_array"
+    )]
+    #[cfg_attr(target_os = "macos", link_section = "__DATA,__mod_init_func")]
+    #[cfg_attr(target_os = "windows", link_section = ".CRT$XCU")]
+    static INIT_CTOR: extern "C" fn() = init_inner;
+
+    /// This is the body of our constructor function.
+    #[cfg_attr(
+        any(target_os = "linux", target_os = "android"),
+        link_section = ".text.startup"
+    )]
+    extern "C" fn init_inner() {
+        INIT.call_once(|| {
+            #[cfg(need_openssl_init)]
+            openssl_sys::init();
+
+            unsafe {
+                assert_eq!(curl_sys::curl_global_init(curl_sys::CURL_GLOBAL_ALL), 0);
+            }
+
+            // Note that we explicitly don't schedule a call to
+            // `curl_global_cleanup`. The documentation for that function says
+            //
+            // > You must not call it when any other thread in the program (i.e.
+            // > a thread sharing the same memory) is running. This doesn't just
+            // > mean no other thread that is using libcurl.
+            //
+            // We can't ever be sure of that, so unfortunately we can't call the
+            // function.
+        });
     }
 
-    #[cfg(not(need_openssl_init))]
-    fn platform_init() {}
+    // We invoke our init function through our static to ensure the symbol isn't
+    // optimized away by a bug: https://github.com/rust-lang/rust/issues/47384
+    INIT_CTOR();
 }
 
 unsafe fn opt_str<'a>(ptr: *const libc::c_char) -> Option<&'a str> {