base_window_stream.hpp

Go to the documentation of this file.

#ifndef GENESIS_POPULATION_WINDOW_BASE_WINDOW_STREAM_H_
#define GENESIS_POPULATION_WINDOW_BASE_WINDOW_STREAM_H_
 
/*
    Genesis - A toolkit for working with phylogenetic data.
    Copyright (C) 2014-2024 Lucas Czech
 
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
 
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
    Contact:
    Lucas Czech <lucas.czech@sund.ku.dk>
    University of Copenhagen, Globe Institute, Section for GeoGenetics
    Oster Voldgade 5-7, 1350 Copenhagen K, Denmark
*/
 
#include "genesis/population/window/window.hpp"
#include "genesis/utils/containers/range.hpp"
#include "genesis/utils/core/std.hpp"
 
#include <cassert>
#include <functional>
#include <memory>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
namespace genesis {
namespace population {
 
// =================================================================================================
//     Base Window Stream
// =================================================================================================
 
template<
    class InputStreamIterator,
    class Data       = typename InputStreamIterator::value_type,
    class WindowType = typename ::genesis::population::Window<Data>
>
class BaseWindowStream
{
public:
 
    // -------------------------------------------------------------------------
    //     Typedefs and Enums
    // -------------------------------------------------------------------------
 
    using InputStreamType   = InputStreamIterator;
    using DataType          = Data;
 
    using self_type         = BaseWindowStream<InputStreamIterator, DataType, WindowType>;
    using InputType         = typename InputStreamIterator::value_type;
 
    using iterator_category = std::input_iterator_tag;
    using value_type        = WindowType;
    using pointer           = value_type*;
    using reference         = value_type&;
    using const_reference   = value_type const&;
 
    // -------------------------------------------------------------------------
    //     Public Functors
    // -------------------------------------------------------------------------
 
    std::function<DataType( InputType const& )> entry_input_function;
 
    std::function<std::string( InputType const& )> chromosome_function;
 
    std::function<size_t( InputType const& )> position_function;
 
    // ======================================================================================
    //      Internal Public Iterator
    // ======================================================================================
 
protected:
 
    // Forward Declaration.
    class BaseIterator;
 
public:
 
    class Iterator final
    {
    public:
 
        // -------------------------------------------------------------------------
        //     Constructors and Rule of Five
        // -------------------------------------------------------------------------
 
        using self_type = typename BaseWindowStream<
            InputStreamType, DataType, WindowType
        >::Iterator;
        using InputType = typename InputStreamType::value_type;
 
        using iterator_category = std::input_iterator_tag;
        using value_type        = WindowType;
        using pointer           = value_type*;
        using reference         = value_type&;
        using const_reference   = value_type const&;
 
        static_assert( std::is_same<Iterator, self_type>::value, "Iterator != self_type" );
 
    protected:
 
        // Iterator() = delete;
 
        Iterator(
            BaseWindowStream const* parent,
            std::unique_ptr<BaseIterator> base_iterator
        )
            : base_parent_( parent )
            , pimpl_( std::move( base_iterator ))
        {
            // Observe the first element, if this is an active iterator.
            assert( pimpl_ );
 
            // If we are here from an end iterator, we do nothing.
            if( !base_parent_ ) {
                return;
            }
            assert( base_parent_ );
 
            // Before starting to init anything, call the callbacks.
            execute_begin_callbacks_();
            execute_on_enter_observers_();
 
            // Special case: no data. Need to execute the end callback as well.
            assert( pimpl_ );
            if( !pimpl_->get_parent_() ) {
                execute_end_callbacks_();
            }
        }
 
    public:
 
        Iterator() = default;
        ~Iterator() = default;
 
        Iterator( Iterator const& ) = delete;
        Iterator( Iterator&& other )
        {
            // Copy the base parent pointer, as that instance stays the same.
            // We however need to move the pimpl, as we own it.
            base_parent_ = other.base_parent_;
            pimpl_ = std::move( other.pimpl_ );
 
            // Now reset the other, so that in case of a bug here, we induce a segfault
            // instead of accidental undefined behaviour when accessing the old data.
            other.base_parent_ = nullptr;
            other.pimpl_ = nullptr;
        }
 
        Iterator& operator= ( Iterator const& ) = delete;
        Iterator& operator= ( Iterator&& other )
        {
            // Same as above.
            // Probably we should follow the rule of five more closely here though,
            // and implement one in terms of the other...
            base_parent_ = other.base_parent_;
            pimpl_ = std::move( other.pimpl_ );
            other.base_parent_ = nullptr;
            other.pimpl_ = nullptr;
            return *this;
        }
 
        friend BaseWindowStream;
 
        // -------------------------------------------------------------------------
        //     Properties
        // -------------------------------------------------------------------------
 
        bool is_first_window() const
        {
            assert( pimpl_ );
            return pimpl_->is_first_window_;
        }
 
        bool is_last_window() const
        {
            assert( pimpl_ );
            return pimpl_->is_last_window_;
        }
 
        // -------------------------------------------------------------------------
        //     Accessors
        // -------------------------------------------------------------------------
 
        value_type const & operator*() const
        {
            assert( pimpl_ );
            return pimpl_->get_current_window_();
        }
 
        value_type & operator*()
        {
            assert( pimpl_ );
            return pimpl_->get_current_window_();
        }
 
        value_type const * operator->() const
        {
            assert( pimpl_ );
            return &( pimpl_->get_current_window_() );
        }
 
        value_type * operator->()
        {
            assert( pimpl_ );
            return &( pimpl_->get_current_window_() );
        }
 
        // -------------------------------------------------------------------------
        //     Iteration
        // -------------------------------------------------------------------------
 
        self_type& operator ++()
        {
            assert( pimpl_ );
            assert( base_parent_ );
 
            // Advance to the next element, and observe it.
            // This is the only place that we need to call the leaving observers:
            // During normal iteration, this works fine anyway. Then, the last iteration
            // will first call the leaving oberservers, then try to move to the next window,
            // but find that there is none, and finish the iteration. By that time, the
            // leaving oberserver has been called correclty already, so nothing else to do.
 
            execute_on_leave_observers_();
            pimpl_->increment_();
 
            // Now that we are at the new element, we execute the enter observers.
            // If we instead reached the end of the input though, that one will do nothing.
            // In that case however, we want to execute the end callbacks instead.
            execute_on_enter_observers_();
 
            assert( pimpl_ );
            assert( base_parent_ );
            if( !pimpl_->get_parent_() ) {
                execute_end_callbacks_();
            }
            return *this;
        }
 
        // self_type operator ++(int)
        // {
        //     auto cpy = *this;
        //     increment_();
        //     return cpy;
        // }
 
        bool operator==( self_type const& other ) const
        {
            assert( pimpl_ );
            assert( other.pimpl_ );
 
            // We compare the parents as a baseline - two past-the-end iterator shall
            // always compare equal. If only one of them is past-the-end, they will compare false.
            return pimpl_->get_parent_() == other.pimpl_->get_parent_();
        }
 
        bool operator!=( self_type const& other ) const
        {
            return !(*this == other);
        }
 
        // -------------------------------------------------------------------------
        //     Internal and Virtual Members
        // -------------------------------------------------------------------------
 
    private:
 
        void execute_on_enter_observers_()
        {
            // If there is still a parent, we are active,
            // and execute all observers for the window.
            assert( pimpl_ );
            if( pimpl_->get_parent_() ) {
                auto& window = pimpl_->get_current_window_();
                for( auto const& observer : pimpl_->get_parent_()->on_enter_observers_ ) {
                    observer( window );
                }
            }
        }
 
        void execute_on_leave_observers_()
        {
            // If there is still a parent, we are active,
            // and execute all observers for the window.
            assert( pimpl_ );
            if( pimpl_->get_parent_() ) {
                auto& window = pimpl_->get_current_window_();
                for( auto const& observer : pimpl_->get_parent_()->on_leave_observers_ ) {
                    observer( window );
                }
            }
        }
 
        void execute_begin_callbacks_() const
        {
            assert( base_parent_ );
            for( auto const& cb : base_parent_->begin_callbacks_ ) {
                cb();
            }
        }
 
        void execute_end_callbacks_() const
        {
            assert( base_parent_ );
            for( auto const& cb : base_parent_->end_callbacks_ ) {
                cb();
            }
        }
 
        // -------------------------------------------------------------------------
        //     PIMPL-like Implementation Abstraction
        // -------------------------------------------------------------------------
 
    private:
 
        // Parent. This is only the base class, and hence cannot be used by the derived classes.
        // We need it here for the begin and end callbacks only, as those need to be run
        // indepentently of the derived classes.
        BaseWindowStream const* base_parent_ = nullptr;
 
        // Implementation of the derived iterator. This is where all the logic for the actual
        // window iteration lives. We use the pimpl idiom here so that this class here does
        // not need to expose derived interfaces.
        std::unique_ptr<BaseIterator> pimpl_;
 
    };
 
    // ======================================================================================
    //      Internal Base Iterator for PIMPL-like Abstraction
    // ======================================================================================
 
protected:
 
    class BaseIterator
    {
    public:
 
        // -------------------------------------------------------------------------
        //     Constructors and Rule of Five
        // -------------------------------------------------------------------------
 
        using self_type = typename BaseWindowStream<
            InputStreamType, DataType, WindowType
        >::BaseIterator;
        using InputType = typename InputStreamType::value_type;
 
        using iterator_category = std::input_iterator_tag;
        using value_type        = WindowType;
        using pointer           = value_type*;
        using reference         = value_type&;
        using const_reference   = value_type const&;
 
        static_assert( std::is_same<BaseIterator, self_type>::value, "BaseIterator != self_type" );
 
    protected:
 
        BaseIterator() = default;
 
        BaseIterator( BaseWindowStream const* parent )
        {
            init_( parent );
        }
 
    public:
 
        virtual ~BaseIterator() = default;
 
        // Abstract base class. Cannot be defaulted, and there is no need to.
        // We leave that to the implementations.
        //
        // BaseIterator( self_type const& ) = default;
        // BaseIterator( self_type&& )      = default;
        // BaseIterator& operator= ( self_type const& ) = default;
        // BaseIterator& operator= ( self_type&& )      = default;
 
        friend BaseWindowStream;
        friend Iterator;
 
        // -------------------------------------------------------------------------
        //     Internal Members
        // -------------------------------------------------------------------------
 
    protected:
 
        void init_( BaseWindowStream const* parent )
        {
            // We use the parent as a check if this Iterator is intended to be a begin()
            // or end() iterator. If its the former, init. If the latter, we are done here.
            // After we are done iterating the input (for which we do need _its_ begin and end
            // iterators), we then set the parent_ to nullptr, as a sign that we are done.
            // This allows us also to know if we reached end() (of the window iteration;
            // not of the underlying data iterator) without having to store the end() iterator
            // when using this class.
            if( ! parent ) {
                return;
            }
 
            // Check that the functors are set up.
            if( ! parent->entry_input_function ) {
                throw std::runtime_error(
                    "Need to set BaseWindowStream::entry_input_function "
                    "before iterating over Windows with a Window Iterator."
                );
            }
            if( ! parent->chromosome_function ) {
                throw std::runtime_error(
                    "Need to set BaseWindowStream::chromosome_function "
                    "before iterating over Windows with a Window Iterator."
                );
            }
            if( ! parent->position_function ) {
                throw std::runtime_error(
                    "Need to set BaseWindowStream::position_function "
                    "before iterating over Windows with a Window Iterator."
                );
            }
 
            // Copy over the underlying data iterator.
            current_ = parent->begin_;
            end_     = parent->end_;
        }
 
        // -------------------------------------------------------------------------
        //     Virtual Members
        // -------------------------------------------------------------------------
 
    protected:
 
        virtual void increment_() = 0;
 
        virtual value_type& get_current_window_() const = 0;
 
        virtual BaseWindowStream const* get_parent_() const = 0;
 
    protected:
 
        // Need to manually keep track of those...
        bool is_first_window_ = true;
        bool is_last_window_ = false;
 
        // Underlying data stream
        InputStreamIterator current_;
        InputStreamIterator end_;
 
    };
 
    // ======================================================================================
    //      Main Class
    // ======================================================================================
 
public:
 
    // -------------------------------------------------------------------------
    //     Constructors and Rule of Five
    // -------------------------------------------------------------------------
 
    BaseWindowStream( InputStreamIterator begin, InputStreamIterator end )
        : begin_(begin)
        , end_(end)
    {}
 
    virtual ~BaseWindowStream() = default;
 
    BaseWindowStream( BaseWindowStream const& ) = default;
    BaseWindowStream( BaseWindowStream&& )      = default;
 
    BaseWindowStream& operator= ( BaseWindowStream const& ) = default;
    BaseWindowStream& operator= ( BaseWindowStream&& )      = default;
 
    friend Iterator;
 
    // -------------------------------------------------------------------------
    //     Observers
    // -------------------------------------------------------------------------
 
    self_type& add_on_enter_observer( std::function<void(WindowType const&)> const& observer )
    {
        on_enter_observers_.push_back( observer );
        return *this;
    }
 
    self_type& add_on_leave_observer( std::function<void(WindowType const&)> const& observer )
    {
        on_leave_observers_.push_back( observer );
        return *this;
    }
 
    self_type& clear_observers()
    {
        on_enter_observers_.clear();
        on_leave_observers_.clear();
        return *this;
    }
 
    self_type& add_begin_callback( std::function<void()> const& callback )
    {
        if( started_ ) {
            throw std::runtime_error(
                "Window Stream: Cannot change callbacks after iteration has started."
            );
        }
        begin_callbacks_.push_back( callback );
        return *this;
    }
 
    self_type& add_end_callback( std::function<void()> const& callback )
    {
        if( started_ ) {
            throw std::runtime_error(
                "Window Stream: Cannot change callbacks after iteration has started."
            );
        }
        end_callbacks_.push_back( callback );
        return *this;
    }
 
    self_type& clear_callbacks()
    {
        if( started_ ) {
            throw std::runtime_error(
                "Window Stream: Cannot change callbacks after iteration has started."
            );
        }
        begin_callbacks_.clear();
        end_callbacks_.clear();
        return *this;
    }
 
    // -------------------------------------------------------------------------
    //     Iteration
    // -------------------------------------------------------------------------
 
    Iterator begin()
    {
        if( started_ ) {
            throw std::runtime_error(
                "Window Stream is an input iterator (single pass), "
                "but begin() has been called multiple times."
            );
        }
        started_ = true;
        return Iterator( this, get_begin_iterator_() );
    }
 
    Iterator end()
    {
        return Iterator( nullptr, get_end_iterator_() );
    }
 
    // -------------------------------------------------------------------------
    //     Virtual Members
    // -------------------------------------------------------------------------
 
protected:
 
    // Need a default for WindowViewStream.
    BaseWindowStream() = default;
 
    virtual std::unique_ptr<BaseIterator> get_begin_iterator_() = 0;
 
    virtual std::unique_ptr<BaseIterator> get_end_iterator_() = 0;
 
    // -------------------------------------------------------------------------
    //     Data Members
    // -------------------------------------------------------------------------
 
private:
 
    // Underlying iterator to the data that we want to put in windows.
    InputStreamIterator begin_;
    InputStreamIterator end_;
    mutable bool started_ = false;
 
    // Keep the observers for each window view.
    std::vector<std::function<void(WindowType const&)>> on_enter_observers_;
    std::vector<std::function<void(WindowType const&)>> on_leave_observers_;
 
    // We furthermore allow callbacks for the beginning and and of the iteration.
    std::vector<std::function<void()>> begin_callbacks_;
    std::vector<std::function<void()>> end_callbacks_;
 
};
 
} // namespace population
} // namespace genesis
 
#endif // include guard