From 1e6f85a5eb5d788683bee33af1178f8fadf2a2cf Mon Sep 17 00:00:00 2001
From: Paul Hauner <paul@paulhauner.com>
Date: Fri, 1 Feb 2019 15:59:12 +1100
Subject: [PATCH] Tidy BlockGraph, use parking_lot, add doc comments

---
 beacon_node/beacon_chain/src/block_graph.rs | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/beacon_node/beacon_chain/src/block_graph.rs b/beacon_node/beacon_chain/src/block_graph.rs
index b031c2c10..5af851243 100644
--- a/beacon_node/beacon_chain/src/block_graph.rs
+++ b/beacon_node/beacon_chain/src/block_graph.rs
@@ -1,12 +1,22 @@
+use parking_lot::{RwLock, RwLockReadGuard};
 use std::collections::HashSet;
-use std::sync::{RwLock, RwLockReadGuard};
 use types::Hash256;
 
+/// Maintains a view of the block DAG, also known as the "blockchain" (except, it tracks multiple
+/// chains eminating from a single root instead of just the head of some canonical chain).
+///
+/// The BlockGraph does not store the blocks, instead it tracks the block hashes of blocks at the
+/// tip of the DAG. It is out of the scope of the object to retrieve blocks.
+///
+/// Presently, the DAG root (genesis block) is not tracked.
+///
+/// The BlogGraph is thread-safe due to internal RwLocks.
 pub struct BlockGraph {
     pub leaves: RwLock<HashSet<Hash256>>,
 }
 
 impl BlockGraph {
+    /// Create a new block graph without any leaves.
     pub fn new() -> Self {
         Self {
             leaves: RwLock::new(HashSet::new()),
@@ -15,10 +25,7 @@ impl BlockGraph {
     /// Add a new leaf to the block hash graph. Returns `true` if the leaf was built upon another
     /// leaf.
     pub fn add_leaf(&self, parent: &Hash256, leaf: Hash256) -> bool {
-        let mut leaves = self
-            .leaves
-            .write()
-            .expect("CRITICAL: BlockGraph poisioned.");
+        let mut leaves = self.leaves.write();
 
         if leaves.contains(parent) {
             leaves.remove(parent);
@@ -30,7 +37,8 @@ impl BlockGraph {
         }
     }
 
+    /// Returns a read-guarded HashSet of all leaf blocks.
     pub fn leaves(&self) -> RwLockReadGuard<HashSet<Hash256>> {
-        self.leaves.read().expect("CRITICAL: BlockGraph poisioned.")
+        self.leaves.read()
     }
 }