summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorMatthias Beyer <mail@beyermatthias.de>2021-04-04 16:08:39 +0200
committerMatthias Beyer <mail@beyermatthias.de>2021-04-04 16:08:39 +0200
commit51d82ced3564aa2f4e49aab6fdeb814652de084a (patch)
treea0fc889479be3b9ace8d3ebcaf28b0c8edc2e212 /src
parent359be3143008faed4bc2d467b5c2a4e62bc6bfdc (diff)
Add documentation
Signed-off-by: Matthias Beyer <mail@beyermatthias.de>
Diffstat (limited to 'src')
-rw-r--r--src/async_dag.rs26
-rw-r--r--src/dag_backend.rs17
-rw-r--r--src/node.rs1
-rw-r--r--src/node_id.rs1
4 files changed, 40 insertions, 5 deletions
diff --git a/src/async_dag.rs b/src/async_dag.rs
index 20a3239..66d79fc 100644
--- a/src/async_dag.rs
+++ b/src/async_dag.rs
@@ -31,6 +31,7 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
N: Node<Id = Id>,
Backend: DagBackend<Id, N>
{
+ /// Create a new DAG with a backend and a HEAD node
pub async fn new(backend: Backend, head: N) -> Result<Self> {
backend
.get(head.id().clone())
@@ -45,6 +46,7 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
.ok_or_else(|| anyhow!("Head not found in backend"))
}
+ /// Check whether an `id` is in the DAG.
pub async fn has_id(&self, id: &Id) -> Result<bool> {
self.stream()
.map(|r| -> Result<bool> {
@@ -83,6 +85,13 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
.collect()
}
+ /// Iterate over the DAG
+ ///
+ /// This function returns a Stream over all nodes in the DAG.
+ ///
+ /// # Warning
+ ///
+ /// The order of the nodes is not (yet) guaranteed.
pub fn stream(&self) -> Stream<Id, N, Backend> {
Stream {
dag: self,
@@ -94,6 +103,11 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
}
}
+ /// Update the HEAD pointer of the DAG
+ ///
+ /// # Warning
+ ///
+ /// fails if the passed node does not point to the current HEAD in its parents.
pub async fn update_head(&mut self, node: N) -> Result<Id> {
if node.parent_ids().iter().any(|id| id == &self.head) {
self.update_head_unchecked(node).await
@@ -102,6 +116,12 @@ impl<Id, N, Backend> AsyncDag<Id, N, Backend>
}
}
+ /// Update the HEAD pointer of the DAG, unchecked
+ ///
+ /// # Warning
+ ///
+ /// Does not check whether the passed `node` does point to the current (then old) HEAD in its
+ /// parents. Be careful to not lose nodes from the DAG with this.
pub async fn update_head_unchecked(&mut self, node: N) -> Result<Id> {
let id = self.backend.put(node).await?;
self.head = id.clone();
@@ -143,7 +163,7 @@ pub trait Merger<Id, N>
fn create_merge_node(&self, left_id: &Id, right_id: &Id) -> Result<N>;
}
-
+/// Stream adapter for streaming all nodes in a DAG
pub struct Stream<'a, Id, N, Backend>
where Id: NodeId + Send,
N: Node<Id = Id>,
@@ -158,12 +178,8 @@ impl<'a, Id, N, Backend> futures::stream::Stream for Stream<'a, Id, N, Backend>
N: Node<Id = Id>,
Backend: DagBackend<Id, N>
{
-
type Item = Result<N>;
- /// Attempt to resolve the next item in the stream.
- /// Returns `Poll::Pending` if not ready, `Poll::Ready(Some(x))` if a value
- /// is ready, and `Poll::Ready(None)` if the stream has completed.
fn poll_next(mut self: std::pin::Pin<&mut Self>, cx: &mut futures::task::Context<'_>) -> futures::task::Poll<Option<Self::Item>> {
if let Some(mut fut) = self.as_mut().backlog.pop() {
match fut.as_mut().poll(cx) {
diff --git a/src/dag_backend.rs b/src/dag_backend.rs
index a91a8ec..62b2cef 100644
--- a/src/dag_backend.rs
+++ b/src/dag_backend.rs
@@ -10,12 +10,29 @@ use async_trait::async_trait;
use crate::NodeId;
use crate::Node;
+/// An interface to a DAG backend storage
+///
+/// A DAG backend storage is nothing more than a thing that can store (`DagBackend::put`) and load
+/// (`DagBackend::get`) nodes.
#[async_trait]
pub trait DagBackend<Id, N>
where N: Node,
Id: NodeId + Send
{
+
+ /// Get a `Node` from the backend that is identified by `id`
+ ///
+ /// # Returns
+ ///
+ /// * Should return Err(_) if the operation failed.
+ /// * Should return Ok(None) if there is no node that is identified by `id`
+ ///
+ /// Otherwise Ok(Some(node)).
async fn get(&self, id: Id) -> Result<Option<N>>;
+
+ /// Store a `node` in the backend, returning its `Id`
+ ///
+ /// This function should store the `node` in the backend and return the `id` the node has.
async fn put(&mut self, node: N) -> Result<Id>;
}
diff --git a/src/node.rs b/src/node.rs
index b557928..da57fb8 100644
--- a/src/node.rs
+++ b/src/node.rs
@@ -6,6 +6,7 @@
use crate::NodeId;
+/// A Node in the DAG, holding the data.
pub trait Node {
type Id: NodeId;
diff --git a/src/node_id.rs b/src/node_id.rs
index d849310..0ee7b97 100644
--- a/src/node_id.rs
+++ b/src/node_id.rs
@@ -4,5 +4,6 @@
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
//
+/// A unique identifier for a `Node`
pub trait NodeId: Clone + Eq + PartialEq + std::hash::Hash {
}