transactional_iterator 0.4.0

#![doc = include_str!("../README.md")]

/// A Transaction refers to the original iterator and clones a working/backup copy of that.
/// This allows to commit or rollback changes made to the iterator.
///
/// Many methods are optimized/specialized for the three polices and thus appear thrice in
/// the API.
#[allow(private_bounds)]
pub struct Transaction<'a, T: Iterator + Clone, P: Policy> {
    original_iter: &'a mut T,
    iter: T,
    policy: P,
}

/*
 * Generic over Policy
 */

#[allow(private_bounds)]
impl<'a, T: Iterator + Clone, P: Policy> Transaction<'a, T, P> {
    /// Create a new transaction with the supplied policy.  This method is provided when one
    /// wants to create a transaction that is generic over one of tree policies.
    ///
    /// # Arguments
    ///
    /// * `iter` - The original iterator.
    /// * `policy` - The policy to use.
    ///
    /// # Returns
    ///
    /// A new transactional iterator.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::{Transaction, Rollback};
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new(&mut iter, Rollback);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    #[must_use]
    pub fn new(iter: &'a mut T, policy: P) -> Self {
        let new_iter = iter.clone();
        Transaction {
            original_iter: iter,
            iter: new_iter,
            policy,
        }
    }
}

#[allow(private_bounds)]
impl<T: Iterator + Clone, P: Policy> Transaction<'_, T, P> {
    /// Create a nested transaction. Transactions can not be 'Clone' as cloning works over
    /// immutable references. To commit, rollback or reset a transaction we need a mutable
    /// reference to its original iterator. Nested transactions have the same policy as their
    /// parent.
    ///
    /// # Returns
    ///
    /// A new, nested `Transaction`.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::{Transaction, Panic};
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    /// let mut transaction = Transaction::new(&mut iter, Panic);
    /// assert_eq!(transaction.next(), Some(1));
    ///
    /// let mut nested_transaction = transaction.nest();
    /// assert_eq!(nested_transaction.next(), Some(2));
    ///
    /// let mut nested_transaction2 = nested_transaction.nest();
    /// assert_eq!(nested_transaction2.next(), Some(3));
    /// nested_transaction2.commit();
    ///
    /// nested_transaction.rollback();
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(2));
    /// ```
    #[must_use]
    pub fn nest(&mut self) -> Transaction<'_, T, P> {
        let iter = self.iter.clone();
        Transaction {
            original_iter: &mut self.iter,
            iter,
            policy: self.policy.clone(),
        }
    }
}

unsafe impl<T: Send + Iterator + Clone, P: Policy> Send for Transaction<'_, T, P> {}

// # Implementation Notes
//
// Depending on the Policy we have different specializations:
//
//  * Panic will iterate over the cloned iterator and panic on drop if not committed or
//    rolled back. The original iterator is left unchanged when dropping/panicking.
//    `Panic` itself has a `Drop` implementation that will panic when not already panicking.
//    `commit` and `rollback` will `forget(policy)` to eliminate this panic.
//
//  * Rollback will iterate over the cloned iterator. The original iterator is left unchanged
//    when dropping or a panic happens.
//
//  * AutoCommit will iterate over the original iterator. This makes commit and drop a no-op
//    and rollback/reset restores the original iterator. When a panic happens the original
//    iterator reflects all changes up to the panic.

/*
 * Panic on drop
 */

impl<'a, T: Iterator + Clone> Transaction<'a, T, Panic> {
    /// Create a new transaction with a `Panic` policy.
    ///
    /// # Arguments
    ///
    /// * `iter` - The original iterator.
    ///
    /// # Returns
    ///
    /// A new transactional iterator. These transactions must be committed or rolled back
    /// otherwise they will panic when dropped (if not already panicking). This will give a
    /// forced backtrace in debug mode. The original iterator is left unchanged in that case.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_panic(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    #[must_use]
    pub fn new_panic(iter: &'a mut T) -> Self {
        let new_iter = iter.clone();
        Transaction {
            original_iter: iter,
            iter: new_iter,
            policy: Panic,
        }
    }

    /// Commit the changes made to the iterator.
    /// The changes are copied to the original iterator.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_panic(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    pub fn commit(self) {
        let Transaction {
            original_iter,
            iter,
            policy,
        } = self;
        *original_iter = iter;
        std::mem::forget(policy);
    }

    /// Rollback the changes made to the iterator. The original iterator is left unchanged.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_panic(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.rollback();
    ///
    /// assert_eq!(iter.next(), Some(1));
    /// ```
    pub fn rollback(self) {
        let Transaction { policy, .. } = self;
        std::mem::forget(policy);
    }

    #[deprecated = "use rollback"]
    #[doc(hidden)]
    pub fn abort(self) {
        self.rollback();
    }

    /// Restarts the transaction. The iterator is reset to the state it was when the
    /// transaction was created.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_panic(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    ///
    /// transaction.reset();
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    pub fn reset(&mut self) {
        self.iter = self.original_iter.clone();
    }

    /// Call a closure on the iterator. When the function returns successful, the transaction
    /// is committed, otherwise it is rolled back. This closure can return a `Result`, `Option`,
    /// `bool` or `()`.
    ///
    /// # Arguments
    ///
    /// * `f` - the closure to call with a mutable reference to the transaction.
    ///
    /// # Returns
    ///
    /// The result of the function.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_panic(&mut iter);
    /// assert_eq!(
    ///     transaction.call(|iter| {
    ///         match iter.next() {
    ///             Some(value) => Ok(value),
    ///             None => Err("No Value"),
    ///         }
    ///     }),
    ///     Ok(1)
    /// );
    ///
    /// assert_eq!(iter.next(), Some(2));
    /// ```
    #[allow(private_bounds)]
    pub fn call<S: IsSuccess>(mut self, f: impl FnOnce(&mut Self) -> S) -> S {
        let result = f(&mut self);
        if result.is_success() {
            self.commit();
        } else {
            self.rollback();
        }
        result
    }
}

impl<'a, T: Iterator + Clone> Iterator for Transaction<'a, T, Panic> {
    type Item = T::Item;

    #[inline(always)]
    fn next(&mut self) -> Option<Self::Item> {
        self.iter.next()
    }
}

/*
 * Rollback on drop
 */

impl<'a, T: Iterator + Clone> Transaction<'a, T, Rollback> {
    /// Create a new transaction that rolls back when dropped or panicking.
    ///
    /// # Arguments
    ///
    /// * `iter` - The original iterator.
    ///
    /// # Returns
    ///
    /// A new transactional iterator.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_rollback(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    ///
    /// assert_eq!(iter.next(), Some(1));
    /// ```
    #[must_use]
    pub fn new_rollback(iter: &'a mut T) -> Self {
        let new_iter = iter.clone();
        Transaction {
            original_iter: iter,
            iter: new_iter,
            policy: Rollback,
        }
    }

    #[deprecated = "use new_rollback"]
    #[doc(hidden)]
    pub fn new_abort(iter: &'a mut T) -> Self {
        Self::new_rollback(iter)
    }

    /// Commit the changes made to the iterator.
    /// The changes are copied to the original iterator.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_rollback(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    pub fn commit(self) {
        let Transaction {
            original_iter,
            iter,
            ..
        } = self;
        *original_iter = iter;
    }

    /// Rollback the changes made to the iterator. The original iterator is left unchanged.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_rollback(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.rollback();
    ///
    /// assert_eq!(iter.next(), Some(1));
    /// ```
    #[inline]
    pub fn rollback(self) {
        /*NOP*/
    }

    #[deprecated = "use rollback"]
    #[doc(hidden)]
    pub fn abort(self) {
        /*NOP*/
    }

    /// Restarts the transaction. The iterator is reset to the state it was when the
    /// transaction was created.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_rollback(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    ///
    /// transaction.reset();
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    pub fn reset(&mut self) {
        self.iter = self.original_iter.clone();
    }

    /// Call a closure on the iterator. When the function returns successful, the transaction
    /// is committed, otherwise it is rolled back. This closure can return a `Result`, `Option`,
    /// `bool` or `()`.
    ///
    /// # Arguments
    ///
    /// * `f` - the closure to call with a mutable reference to the transaction.
    ///
    /// # Returns
    ///
    /// The result of the function.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_rollback(&mut iter);
    /// assert_eq!(
    ///     transaction.call(|iter| {
    ///         match iter.next() {
    ///             Some(value) => Ok(value),
    ///             None => Err("No Value"),
    ///         }
    ///     }),
    ///     Ok(1)
    /// );
    ///
    /// assert_eq!(iter.next(), Some(2));
    /// ```
    #[allow(private_bounds)]
    pub fn call<S: IsSuccess>(mut self, f: impl FnOnce(&mut Self) -> S) -> S {
        let result = f(&mut self);
        if result.is_success() {
            self.commit();
        } else {
            self.rollback();
        }
        result
    }
}

impl<'a, T: Iterator + Clone> Iterator for Transaction<'a, T, Rollback> {
    type Item = T::Item;

    #[inline(always)]
    fn next(&mut self) -> Option<Self::Item> {
        self.iter.next()
    }
}

/*
 * AutoCommit on drop
 */

impl<'a, T: Iterator + Clone> Transaction<'a, T, AutoCommit> {
    /// Create a new transaction that commits automatically when dropped or panicking.  This
    /// is implemented by iterating the original iterator. Commit and drop are no-ops, rollback
    /// and reset will restore the original iterator.
    ///
    /// # Arguments
    ///
    /// * `iter` - The original iterator.
    ///
    /// # Returns
    ///
    /// A new transactional iterator.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_autocommit(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    #[must_use]
    pub fn new_autocommit(iter: &'a mut T) -> Self {
        let new_iter = iter.clone();
        Transaction {
            original_iter: iter,
            iter: new_iter,
            policy: AutoCommit,
        }
    }

    /// Commit the changes made to the iterator.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_autocommit(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    #[inline]
    pub fn commit(self) {
        /*NOP*/
    }

    /// Rollback the changes made to the iterator. The original iterator becomes restored.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_autocommit(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.rollback();
    ///
    /// assert_eq!(iter.next(), Some(1));
    /// ```
    pub fn rollback(self) {
        let Transaction {
            original_iter,
            iter,
            ..
        } = self;
        *original_iter = iter;
    }

    #[deprecated = "use rollback"]
    #[doc(hidden)]
    pub fn abort(self) {
        self.rollback();
    }

    /// Restarts the transaction. The iterator is reset to the state it was when the
    /// transaction was created.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_autocommit(&mut iter);
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    ///
    /// transaction.reset();
    /// assert_eq!(transaction.next(), Some(1));
    /// assert_eq!(transaction.next(), Some(2));
    /// transaction.commit();
    ///
    /// assert_eq!(iter.next(), Some(3));
    /// ```
    pub fn reset(&mut self) {
        *self.original_iter = self.iter.clone();
    }

    /// Call a closure on the iterator. When the function returns successful, the transaction
    /// is committed, otherwise it is rolled back. This closure can return a `Result`, `Option`,
    /// `bool` or `()`.
    ///
    /// # Arguments
    ///
    /// * `f` - the closure to call with a mutable reference to the transaction.
    ///
    /// # Returns
    ///
    /// The result of the function.
    ///
    /// # Example
    ///
    /// ```
    /// use transactional_iterator::Transaction;
    ///
    /// let mut iter = vec![1, 2, 3].into_iter();
    ///
    /// let mut transaction = Transaction::new_autocommit(&mut iter);
    /// assert_eq!(
    ///     transaction.call(|iter| {
    ///         match iter.next() {
    ///             Some(value) => Ok(value),
    ///             None => Err("No Value"),
    ///         }
    ///     }),
    ///     Ok(1)
    /// );
    ///
    /// assert_eq!(iter.next(), Some(2));
    /// ```
    #[allow(private_bounds)]
    pub fn call<S: IsSuccess>(mut self, f: impl FnOnce(&mut Self) -> S) -> S {
        let result = f(&mut self);
        if result.is_success() {
            self.commit();
        } else {
            self.rollback();
        }
        result
    }
}

impl<'a, T: Iterator + Clone> Iterator for Transaction<'a, T, AutoCommit> {
    type Item = T::Item;

    #[inline(always)]
    fn next(&mut self) -> Option<Self::Item> {
        self.original_iter.next()
    }
}

/// The policy that tags a transaction to auto commit changes on drop or panic.
#[derive(Clone)]
pub struct AutoCommit;

/// The policy that tags a transaction to roll back changes on drop or panic.
#[derive(Clone)]
pub struct Rollback;

#[deprecated = "use Rollback"]
#[doc(hidden)]
pub type Abort = Rollback;

/// The policy that tags a transaction to panic on drop.
#[derive(Clone)]
pub struct Panic;

impl Drop for Panic {
    #[cold]
    fn drop(&mut self) {
        if !std::thread::panicking() {
            #[cfg(debug_assertions)]
            panic!(
                "Transaction not committed or rolled back\n{}",
                std::backtrace::Backtrace::force_capture()
            );
            #[cfg(not(debug_assertions))]
            panic!("Transaction not committed or rolled back");
        }
    }
}

mod sealed {
    pub trait Sealed {}
}
use sealed::Sealed;

impl Sealed for Panic {}
impl Sealed for Rollback {}
impl Sealed for AutoCommit {}

/// A trait for the three policies. This allows user code to be generic over the policy.
pub trait Policy: Clone + Sealed {}

impl Policy for Panic {}
impl Policy for Rollback {}
impl Policy for AutoCommit {}

/// A trait to check if a (return) value signifies success. This trait is implemented for
/// `Option`, `Result`, `bool` and `()`. This can be implemented in user code.
pub trait IsSuccess {
    /// returns 'true' for success.
    fn is_success(&self) -> bool;
}

/// Successful for `Some()`
impl<T> IsSuccess for Option<T> {
    #[inline]
    fn is_success(&self) -> bool {
        self.is_some()
    }
}

/// Successful for `Ok()`
impl<T, E> IsSuccess for Result<T, E> {
    #[inline]
    fn is_success(&self) -> bool {
        self.is_ok()
    }
}

/// Successful for `true`
impl IsSuccess for bool {
    #[inline]
    fn is_success(&self) -> bool {
        *self
    }
}

/// Always successful
impl IsSuccess for () {
    #[inline]
    fn is_success(&self) -> bool {
        true
    }
}

#[test]
#[should_panic = "Transaction not committed or rolled back"]
fn test_transaction_uncommited_panics() {
    let mut iter = vec![1, 2, 3].into_iter();
    let mut transaction = Transaction::new(&mut iter, Panic);
    assert_eq!(transaction.next(), Some(1));
    drop(transaction);
    assert_eq!(iter.next(), Some(1));
}

#[test]
fn test_transaction_rollback() {
    let mut iter = vec![1, 2, 3].into_iter();
    let mut transaction = Transaction::new(&mut iter, Panic);
    assert_eq!(transaction.next(), Some(1));
    transaction.rollback();
    assert_eq!(iter.next(), Some(1));
}

#[test]
fn test_nested_transaction() {
    let mut iter = vec![1, 2, 3].into_iter();
    let mut transaction = Transaction::new(&mut iter, Panic);
    assert_eq!(transaction.next(), Some(1));

    let mut nested_transaction = transaction.nest();
    assert_eq!(nested_transaction.next(), Some(2));

    let mut nested_transaction2 = nested_transaction.nest();
    assert_eq!(nested_transaction2.next(), Some(3));
    nested_transaction2.commit();

    nested_transaction.commit();
    transaction.commit();

    assert_eq!(iter.next(), None);
}