utl/include/utl/container/equeue.h

/*!
 * \file container/equeue.h
 * \brief
 *      A queue with event based callables based on edeque.
 *
 * \copyright Copyright (C) 2021 Christos Choutouridis <christos@choutouridis.net>
 *
 * <dl class=\"section copyright\"><dt>License</dt><dd>
 * The MIT License (MIT)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 * </dd></dl>
 */

#ifndef utl_container_equeue_h__
#define utl_container_equeue_h__

#include <utl/core/impl.h>
#include <utl/container/edeque.h>

namespace utl {

/*!
 * \class equeue
 * \brief
 *      A statically allocated queue based on edeque with size and data matching
 *      event based callables.
 *
 * We use the \ref edeque::push_back() and \ref edeque::pop_front() pair from edeque's
 * functionality, so at the \c push the increment performed after the insertion.
 * Similarly at the \c pop the decrement performed before the exctraction. This way also
 * the \ref edeque::front() and \ref edeque::back() stay the same ;)
 *
 * We also provide stream operators.
 *
 * \tparam Data_t       The char-like queued item type. Usually \c char
 * \tparam N            The size of edeque
 * \tparam SemiAtomic   True for semi-atomic operation. In that case the \c ring_iterator is also atomic.
 * \tparam Fn           The type of Callable
 * \note
 *      SemiAtomic means it is safe to for one thread to  push only from front and another can pop.
 */
template <typename Data_t, size_t N, bool SemiAtomic =false, typename Fn = std::function<void()>>
class equeue : public edeque<Data_t, N, SemiAtomic, Fn> {
    public:
        // meta-identity types
        using equeue_t              = equeue<Data_t, N, SemiAtomic, Fn>;
        using base_type             = edeque<Data_t, N, SemiAtomic, Fn>;
        using range_t               = typename base_type::range_t;

        // STL
        using value_type            = typename base_type::value_type;
        using reference             = typename base_type::reference;
        using const_reference       = typename base_type::const_reference;
        using pointer               = typename base_type::pointer;
        using const_pointer         = typename base_type::const_pointer;
        using iterator              = typename base_type::iterator;
        using const_iterator        = typename base_type::const_iterator;
        using reverse_iterator      = typename base_type::reverse_iterator;
        using const_reverse_iterator= typename base_type::const_reverse_iterator;

    //! \name Constructor / Destructor
    //! @{
    public:
        //! Default constructor
        constexpr equeue () noexcept : base_type() { }

        //! Forward constructor
        template <typename ...It>
        constexpr equeue(It&& ...it) noexcept : base_type(std::forward<It>(it)...) { }

    //! @}

    //! \name Member access
    //! @{
    public:
        //! \brief      Push an item in the back of the queue
        //! \param it   The item to push
        void push (const Data_t& it) noexcept {
            base_type::push_back(it);
        }

        //! \brief      Extract an item from the front of the queue and remove it from the queue
        //! \param it   The item to push
        Data_t pop () noexcept {
            return base_type::pop_front();
        }

        //! \brief      Push an item in the back of the queue
        //! \param it   The item to push
        equeue_t& operator<< (const Data_t& it) noexcept {
            push(it);
            return *this;
        }

        //! \brief      Push an item in the back of the queue
        //! \param it   The item to push
        equeue_t& operator>> (Data_t& it) noexcept {
            it = pop();
            return *this;
        }

    //! @}

};

/*!
 * \brief
 *      Pop an item from the front of the queue.
 *
 *  This definition enables the "data << equeue" syntax for pop operation
 *
 *  \tparam Data_t      The char-like queued item type. Usually \c char
 *  \tparam N           The size of queue
 *  \tparam SemiAtomic  True for semi-atomic operation. In that case the \c ring_iterator is also atomic.
 *  \tparam Fn          The type of Callable
 *
 *  \param it       The item to write to
 *  \param q        The queue to read from
 *  \return         Reference to the returned item
 */
template <typename Data_t, size_t N, bool SemiAtomic =false, typename Fn = std::function<void()>>
Data_t& operator<< (Data_t& it, equeue<Data_t, N, SemiAtomic, Fn>& q) noexcept {
    it = q.pop();
    return it;
}

} // namespace utl

#endif /* utl_container_equeue_h__ */