Merge branch 'master' into stable_vec

Author: blkerby

.github/workflows/main.yml

@@ -6,7 +6,7 @@ jobs:
     name: Test
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v2
     - name: Update rustup
       run: rustup self update
     - name: Install Rust
@@ -15,10 +15,12 @@ jobs:
         rustup toolchain install nightly -c rust-docs
         rustup default nightly
     - name: Install mdbook
+      env:
+        MDBOOK_VER: v0.4.3
       run: |
         mkdir bin
-        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.3.5/mdbook-v0.3.5-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
-        echo "##[add-path]$(pwd)/bin"
+        curl -sSL https://github.com/rust-lang/mdBook/releases/download/${{ env.MDBOOK_VER }}/mdbook-${{ env.MDBOOK_VER }}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+        echo "$(pwd)/bin" >> $GITHUB_PATH
     - name: Report versions
       run: |
         rustup --version

.gitignore

@@ -1,2 +1,7 @@
 *.html
 book
+
+# linkcheck stuff
+linkcheck
+linkchecker
+linkcheck.sh

src/SUMMARY.md

@@ -3,58 +3,64 @@
 [Introduction](README.md)
 
 * [Meet Safe and Unsafe](meet-safe-and-unsafe.md)
-	* [How Safe and Unsafe Interact](safe-unsafe-meaning.md)
-	* [What Unsafe Can Do](what-unsafe-does.md)
-	* [Working with Unsafe](working-with-unsafe.md)
+    * [How Safe and Unsafe Interact](safe-unsafe-meaning.md)
+    * [What Unsafe Can Do](what-unsafe-does.md)
+    * [Working with Unsafe](working-with-unsafe.md)
 * [Data Layout](data.md)
-	* [repr(Rust)](repr-rust.md)
-	* [Exotically Sized Types](exotic-sizes.md)
-	* [Other reprs](other-reprs.md)
+    * [repr(Rust)](repr-rust.md)
+    * [Exotically Sized Types](exotic-sizes.md)
+    * [Other reprs](other-reprs.md)
 * [Ownership](ownership.md)
-	* [References](references.md)
-	* [Aliasing](aliasing.md)
-	* [Lifetimes](lifetimes.md)
-	* [Limits of Lifetimes](lifetime-mismatch.md)
-	* [Lifetime Elision](lifetime-elision.md)
-	* [Unbounded Lifetimes](unbounded-lifetimes.md)
-	* [Higher-Rank Trait Bounds](hrtb.md)
-	* [Subtyping and Variance](subtyping.md)
-	* [Drop Check](dropck.md)
-	* [PhantomData](phantom-data.md)
-	* [Splitting Borrows](borrow-splitting.md)
+    * [References](references.md)
+    * [Aliasing](aliasing.md)
+    * [Lifetimes](lifetimes.md)
+    * [Limits of Lifetimes](lifetime-mismatch.md)
+    * [Lifetime Elision](lifetime-elision.md)
+    * [Unbounded Lifetimes](unbounded-lifetimes.md)
+    * [Higher-Rank Trait Bounds](hrtb.md)
+    * [Subtyping and Variance](subtyping.md)
+    * [Drop Check](dropck.md)
+    * [PhantomData](phantom-data.md)
+    * [Splitting Borrows](borrow-splitting.md)
 * [Type Conversions](conversions.md)
-	* [Coercions](coercions.md)
-	* [The Dot Operator](dot-operator.md)
-	* [Casts](casts.md)
-	* [Transmutes](transmutes.md)
+    * [Coercions](coercions.md)
+    * [The Dot Operator](dot-operator.md)
+    * [Casts](casts.md)
+    * [Transmutes](transmutes.md)
 * [Uninitialized Memory](uninitialized.md)
-	* [Checked](checked-uninit.md)
-	* [Drop Flags](drop-flags.md)
-	* [Unchecked](unchecked-uninit.md)
+    * [Checked](checked-uninit.md)
+    * [Drop Flags](drop-flags.md)
+    * [Unchecked](unchecked-uninit.md)
 * [Ownership Based Resource Management](obrm.md)
-	* [Constructors](constructors.md)
-	* [Destructors](destructors.md)
-	* [Leaking](leaking.md)
+    * [Constructors](constructors.md)
+    * [Destructors](destructors.md)
+    * [Leaking](leaking.md)
 * [Unwinding](unwinding.md)
-	* [Exception Safety](exception-safety.md)
-	* [Poisoning](poisoning.md)
+    * [Exception Safety](exception-safety.md)
+    * [Poisoning](poisoning.md)
 * [Concurrency](concurrency.md)
-	* [Races](races.md)
-	* [Send and Sync](send-and-sync.md)
-	* [Atomics](atomics.md)
+    * [Races](races.md)
+    * [Send and Sync](send-and-sync.md)
+    * [Atomics](atomics.md)
 * [Implementing Vec](vec.md)
-	* [Layout](vec-layout.md)
-	* [Allocating](vec-alloc.md)
-	* [Push and Pop](vec-push-pop.md)
-	* [Deallocating](vec-dealloc.md)
-	* [Deref](vec-deref.md)
-	* [Insert and Remove](vec-insert-remove.md)
-	* [IntoIter](vec-into-iter.md)
-	* [RawVec](vec-raw.md)
-	* [Drain](vec-drain.md)
-	* [Handling Zero-Sized Types](vec-zsts.md)
-	* [Final Code](vec-final.md)
+    * [Layout](vec-layout.md)
+    * [Allocating](vec-alloc.md)
+    * [Push and Pop](vec-push-pop.md)
+    * [Deallocating](vec-dealloc.md)
+    * [Deref](vec-deref.md)
+    * [Insert and Remove](vec-insert-remove.md)
+    * [IntoIter](vec-into-iter.md)
+    * [RawVec](vec-raw.md)
+    * [Drain](vec-drain.md)
+    * [Handling Zero-Sized Types](vec-zsts.md)
+    * [Final Code](vec-final.md)
 * [Implementing Arc and Mutex](arc-and-mutex.md)
+    * [Arc](arc.md)
+      * [Layout](arc-layout.md)
+      * [Base Code](arc-base.md)
+      * [Cloning](arc-clone.md)
+      * [Dropping](arc-drop.md)
+      * [Final Code](arc-final.md)
 * [FFI](ffi.md)
 * [Beneath `std`](beneath-std.md)
-	* [#[panic_handler]](panic-handler.md)
+    * [#[panic_handler]](panic-handler.md)

src/arc-and-mutex.md

@@ -4,4 +4,4 @@ Knowing the theory is all fine and good, but the *best* way to understand
 something is to use it. To better understand atomics and interior mutability,
 we'll be implementing versions of the standard library's Arc and Mutex types.
 
-TODO: ALL OF THIS OMG
+TODO: Mutex

src/arc-base.md

@@ -0,0 +1,136 @@
+# Base Code
+
+Now that we've decided the layout for our implementation of `Arc`, let's create
+some basic code.
+
+## Constructing the Arc
+
+We'll first need a way to construct an `Arc<T>`.
+
+This is pretty simple, as we just need to box the `ArcInner<T>` and get a
+`NonNull<T>` pointer to it.
+
+```rust,ignore
+impl<T> Arc<T> {
+    pub fn new(data: T) -> Arc<T> {
+        // We start the reference count at 1, as that first reference is the
+        // current pointer.
+        let boxed = Box::new(ArcInner {
+            rc: AtomicUsize::new(1),
+            data,
+        });
+        Arc {
+            // It is okay to call `.unwrap()` here as we get a pointer from
+            // `Box::into_raw` which is guaranteed to not be null.
+            ptr: NonNull::new(Box::into_raw(boxed)).unwrap(),
+            phantom: PhantomData,
+        }
+    }
+}
+```
+
+## Send and Sync
+
+Since we're building a concurrency primitive, we'll need to be able to send it
+across threads. Thus, we can implement the `Send` and `Sync` marker traits. For
+more information on these, see [the section on `Send` and
+`Sync`](send-and-sync.md).
+
+This is okay because:
+* You can only get a mutable reference to the value inside an `Arc` if and only
+  if it is the only `Arc` referencing that data (which only happens in `Drop`)
+* We use atomics for the shared mutable reference counting
+
+```rust,ignore
+unsafe impl<T: Sync + Send> Send for Arc<T> {}
+unsafe impl<T: Sync + Send> Sync for Arc<T> {}
+```
+
+We need to have the bound `T: Sync + Send` because if we did not provide those
+bounds, it would be possible to share values that are thread-unsafe across a
+thread boundary via an `Arc`, which could possibly cause data races or
+unsoundness.
+
+For example, if those bounds were not present, `Arc<Rc<u32>>` would be `Sync` or
+`Send`, meaning that you could clone the `Rc` out of the `Arc` to send it across
+a thread (without creating an entirely new `Rc`), which would create data races
+as `Rc` is not thread-safe.
+
+## Getting the `ArcInner`
+
+To dereference the `NonNull<T>` pointer into a `&T`, we can call
+`NonNull::as_ref`. This is unsafe, unlike the typical `as_ref` function, so we
+must call it like this:
+```rust,ignore
+unsafe { self.ptr.as_ref() }
+```
+
+We'll be using this snippet a few times in this code (usually with an associated
+`let` binding).
+
+This unsafety is okay because while this `Arc` is alive, we're guaranteed that
+the inner pointer is valid.
+
+## Deref
+
+Alright. Now we can make `Arc`s (and soon will be able to clone and destroy them correctly), but how do we get
+to the data inside?
+
+What we need now is an implementation of `Deref`.
+
+We'll need to import the trait:
+```rust,ignore
+use std::ops::Deref;
+```
+
+And here's the implementation:
+```rust,ignore
+impl<T> Deref for Arc<T> {
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        let inner = unsafe { self.ptr.as_ref() };
+        &inner.data
+    }
+}
+```
+
+Pretty simple, eh? This simply dereferences the `NonNull` pointer to the
+`ArcInner<T>`, then gets a reference to the data inside.
+
+## Code
+
+Here's all the code from this section:
+```rust,ignore
+use std::ops::Deref;
+
+impl<T> Arc<T> {
+    pub fn new(data: T) -> Arc<T> {
+        // We start the reference count at 1, as that first reference is the
+        // current pointer.
+        let boxed = Box::new(ArcInner {
+            rc: AtomicUsize::new(1),
+            data,
+        });
+        Arc {
+            // It is okay to call `.unwrap()` here as we get a pointer from
+            // `Box::into_raw` which is guaranteed to not be null.
+            ptr: NonNull::new(Box::into_raw(boxed)).unwrap(),
+            phantom: PhantomData,
+        }
+    }
+}
+
+unsafe impl<T: Sync + Send> Send for Arc<T> {}
+unsafe impl<T: Sync + Send> Sync for Arc<T> {}
+
+
+impl<T> Deref for Arc<T> {
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        let inner = unsafe { self.ptr.as_ref() };
+        &inner.data
+    }
+}
+```

src/arc-clone.md

@@ -0,0 +1,94 @@
+# Cloning
+
+Now that we've got some basic code set up, we'll need a way to clone the `Arc`.
+
+Basically, we need to:
+1. Increment the atomic reference count
+2. Construct a new instance of the `Arc` from the inner pointer
+
+First, we need to get access to the `ArcInner`:
+```rust,ignore
+let inner = unsafe { self.ptr.as_ref() };
+```
+
+We can update the atomic reference count as follows:
+```rust,ignore
+let old_rc = inner.rc.fetch_add(1, Ordering::???);
+```
+
+But what ordering should we use here? We don't really have any code that will
+need atomic synchronization when cloning, as we do not modify the internal value
+while cloning. Thus, we can use a Relaxed ordering here, which implies no
+happens-before relationship but is atomic. When `Drop`ping the Arc, however,
+we'll need to atomically synchronize when decrementing the reference count. This
+is described more in [the section on the `Drop` implementation for
+`Arc`](arc-drop.md). For more information on atomic relationships and Relaxed
+ordering, see [the section on atomics](atomics.md).
+
+Thus, the code becomes this:
+```rust,ignore
+let old_rc = inner.rc.fetch_add(1, Ordering::Relaxed);
+```
+
+We'll need to add another import to use `Ordering`:
+```rust,ignore
+use std::sync::atomic::Ordering;
+```
+
+However, we have one problem with this implementation right now. What if someone
+decides to `mem::forget` a bunch of Arcs? The code we have written so far (and
+will write) assumes that the reference count accurately portrays how many Arcs
+are in memory, but with `mem::forget` this is false. Thus, when more and more
+Arcs are cloned from this one without them being `Drop`ped and the reference
+count being decremented, we can overflow! This will cause use-after-free which
+is **INCREDIBLY BAD!**
+
+To handle this, we need to check that the reference count does not go over some
+arbitrary value (below `usize::MAX`, as we're storing the reference count as an
+`AtomicUsize`), and do *something*.
+
+The standard library's implementation decides to just abort the program (as it
+is an incredibly unlikely case in normal code and if it happens, the program is
+probably incredibly degenerate) if the reference count reaches `isize::MAX`
+(about half of `usize::MAX`) on any thread, on the assumption that there are
+probably not about 2 billion threads (or about **9 quintillion** on some 64-bit
+machines) incrementing the reference count at once. This is what we'll do.
+
+It's pretty simple to implement this behaviour:
+```rust,ignore
+if old_rc >= isize::MAX as usize {
+    std::process::abort();
+}
+```
+
+Then, we need to return a new instance of the `Arc`:
+```rust,ignore
+Self {
+    ptr: self.ptr,
+    phantom: PhantomData
+}
+```
+
+Now, let's wrap this all up inside the `Clone` implementation:
+```rust,ignore
+use std::sync::atomic::Ordering;
+
+impl<T> Clone for Arc<T> {
+    fn clone(&self) -> Arc<T> {
+        let inner = unsafe { self.ptr.as_ref() };
+        // Using a relaxed ordering is alright here as we don't need any atomic
+        // synchronization here as we're not modifying or accessing the inner
+        // data.
+        let old_rc = inner.rc.fetch_add(1, Ordering::Relaxed);
+
+        if old_rc >= isize::MAX as usize {
+            std::process::abort();
+        }
+
+        Self {
+            ptr: self.ptr,
+            phantom: PhantomData,
+        }
+    }
+}
+```