Generator.hpp

Go to the documentation of this file.

//
//  CeresEngine - A game development framework
//
//  Created by Rogiel Sulzbach.
//  Copyright (c) 2018-2022 Rogiel Sulzbach. All rights reserved.
//
 
#pragma once
 
#if !defined(__cpp_coroutines) && !defined(__cpp_impl_coroutine)
#error "Generator: Unsupported platform!"
#endif
 
#include "CeresEngine/Macros.hpp"
 
#include "CeresEngine/Foundation/Coroutine.hpp"
#include "CeresEngine/Foundation/Threading/Threading.hpp"
 
#include <iterator>
#include <mutex>
#include <optional>
 
namespace CeresEngine {
 
    template<typename T> class Generator final {
        class Promise;
 
    public: // Coroutine interface
        class Iterator;
 
        using promise_type = Promise;
 
    private:
        using CoroutineHandle = coroutine_handle<Promise>;
 
        using suspend_always = CeresEngine::suspend_always;
 
        using suspend_never = CeresEngine::suspend_never;
 
        // The coroutine handle
        CoroutineHandle mCoroutine;
 
    public:
        Generator() noexcept : mCoroutine(nullptr) {}
 
        Generator(const Generator& other) = delete;
 
        Generator& operator=(const Generator& other) = delete;
 
        Generator(Generator&& other) noexcept : mCoroutine(other.mCoroutine) { other.mCoroutine = nullptr; }
 
        Generator& operator=(Generator&& other) noexcept {
            std::swap(mCoroutine, other.mCoroutine);
            return *this;
        }
 
        ~Generator() {
            if(mCoroutine) {
                mCoroutine.destroy();
            }
        }
 
    private:
        explicit Generator(CoroutineHandle coroutine) noexcept : mCoroutine(coroutine) {}
 
    public:
        [[nodiscard]] Iterator begin() {
            if(mCoroutine) {
                CE_LIKELY {
                    mCoroutine.resume();
                    if(mCoroutine.done()) {
                        CE_UNLIKELY {
                            mCoroutine.promise().rethrow();
                            return Iterator{nullptr};
                        }
                    }
                }
            }
            return Iterator{mCoroutine};
        }
 
        [[nodiscard]] Iterator end() noexcept { return Iterator{nullptr}; }
 
    private:
        class Promise final {
        public:
            using Value = std::remove_reference_t<T>;
 
            using Reference = std::conditional_t<std::is_reference_v<T>, T, T&>;
 
            using Pointer = Value*;
 
        private:
            Pointer mValue = nullptr;
 
            std::exception_ptr mException = nullptr;
 
        public:
            Promise() = default;
 
        public: // Coroutine implementation
            Generator get_return_object() noexcept { return Generator<T>{CoroutineHandle::from_promise(*this)}; }
 
            [[nodiscard]] constexpr suspend_always initial_suspend() const noexcept { return {}; }
 
            [[nodiscard]] constexpr suspend_always final_suspend() const noexcept { return {}; }
 
            template<typename U = T, std::enable_if_t<!std::is_rvalue_reference<U>::value, int> = 0>
            suspend_always yield_value(std::remove_reference_t<T>& aValue) noexcept {
                mValue = std::addressof(aValue);
                return {};
            }
 
            template<typename U = T, std::enable_if_t<!std::is_rvalue_reference<U>::value && !std::is_const_v<U>, int> = 0>
            suspend_always yield_value(const std::remove_reference_t<T>& aValue) noexcept {
                mValue = std::addressof(const_cast<std::remove_reference_t<T>&>(aValue));
                return {};
            }
 
            //            /// Yields a new value to the generator.
            //            /// \param aValue   The value to be yielded to the generator
            //            /// \return `suspend_always`
            //            suspend_always yield_value(std::remove_reference_t<T>&& aValue) noexcept {
            //                mValue = std::addressof(aValue);
            //                return {};
            //            }
 
            void unhandled_exception() noexcept {
                mException = std::current_exception(); // NOLINT
            }
 
            void return_void() noexcept {}
 
            template<typename U> suspend_never await_transform(U&& value) = delete;
 
            [[nodiscard]] Reference getValue() const noexcept { return static_cast<Reference>(*mValue); }
 
            void rethrow() {
                if(mException) {
                    CE_UNLIKELY { std::rethrow_exception(mException); }
                }
            }
        };
 
    public:
        class Iterator final {
        private:
            CoroutineHandle mCoroutine = nullptr;
 
        public:
            Iterator() noexcept : mCoroutine(nullptr) {}
 
            explicit Iterator(CoroutineHandle coroutine) noexcept : mCoroutine(coroutine) {}
 
        public: // Iterator concept
            using iterator_category = std::input_iterator_tag;
            using difference_type = std::ptrdiff_t;
            using value_type = typename Promise::Value;
            using reference = typename Promise::Reference;
            using pointer = typename Promise::Pointer;
 
            [[nodiscard]] bool operator==(const Iterator& other) const noexcept { return mCoroutine.address() == other.mCoroutine.address(); }
 
            [[nodiscard]] bool operator!=(const Iterator& other) const noexcept { return !(*this == other); }
 
            CE_FORCE_INLINE Iterator& operator++() {
                mCoroutine.resume();
                if(mCoroutine.done()) {
                    CE_UNLIKELY {
                        mCoroutine.promise().rethrow();
                        mCoroutine = nullptr;
                    }
                }
                return *this;
            }
 
            CE_FORCE_INLINE void operator++(int) { (void)operator++(); }
 
            [[nodiscard]] reference operator*() const noexcept { return mCoroutine.promise().getValue(); }
 
            [[nodiscard]] pointer operator->() const noexcept { return std::addressof(operator*()); }
        };
    };
 
    template<typename T, typename Lockable = Mutex> class AsyncGenerator final {
        class Promise; // Resumable Promise Requirement
        class Iterator;
 
    public: // Coroutine interface
        using promise_type = Promise;
 
    private:
        using Reference = T&;
        using Pointer = T*;
 
        using CoroutineHandle = coroutine_handle<Promise>;
 
        using AsyncCoroutineHandle = coroutine_handle<>;
 
        using suspend_always = CeresEngine::suspend_always;
 
        using suspend_never = CeresEngine::suspend_never;
 
    private:
        CoroutineHandle mCoroutine; // resumable handle
 
    public:
        AsyncGenerator() noexcept : mCoroutine(nullptr) {}
 
        AsyncGenerator(const AsyncGenerator&) = delete;
 
        AsyncGenerator& operator=(const AsyncGenerator&) = delete;
 
        AsyncGenerator(AsyncGenerator&& other) noexcept : mCoroutine(other.mCoroutine) { other.mCoroutine = nullptr; }
 
        AsyncGenerator& operator=(AsyncGenerator&& other) noexcept {
            std::swap(mCoroutine, other.mCoroutine);
            return *this;
        }
 
        ~AsyncGenerator() noexcept {
            // delete the coroutine frame
            //  coro.done() won't be checked since the usecase might want it
            //  the library only guarantees there is no leak
            if(mCoroutine) {
                mCoroutine.destroy();
            }
        }
 
    private:
        explicit AsyncGenerator(Promise* promise) noexcept : mCoroutine{CoroutineHandle::from_promise(*promise)} {}
 
    public:
        [[nodiscard]] Iterator begin() {
            if(mCoroutine) {
                CE_LIKELY {
                    mCoroutine.resume();
                    if(mCoroutine.done()) {
                        CE_UNLIKELY {
                            mCoroutine.promise().rethrow();
                            return Iterator{nullptr};
                        }
                    }
                }
            }
            return Iterator{mCoroutine};
        }
 
        [[nodiscard]] Iterator end() noexcept { return Iterator{nullptr}; }
 
    private:
        class Promise final {
            friend class Iterator;
            friend class AsyncGenerator;
 
        public:
            std::optional<Pointer> current = nullptr;
 
            std::exception_ptr exception = nullptr;
 
            AsyncCoroutineHandle task = nullptr;
 
            mutable Lockable mutex;
            //
            //        public:
            //            /// Allocates memory for a new instance of `Promise`.
            //            template<typename RawAllocator>
            //            static void* operator new(size_t size, RawAllocator& allocator) noexcept {
            //                return AllocatorTraits<RawAllocator>::allocate_node(allocator, size, alignof(std::max_align_t));
            //            }
            //
            //            /// Deletes memory for an instance of `Promise`.
            //            template<typename RawAllocator>
            //            static void operator delete(void* p, std::size_t sz, RawAllocator& allocator) noexcept {
            //                AllocatorTraits<RawAllocator>::deallocate_node(allocator, p, sz, alignof(std::max_align_t));
            //            }
 
        public:
            AsyncGenerator get_return_object() noexcept { return AsyncGenerator{this}; }
 
            constexpr suspend_always initial_suspend() const noexcept { return {}; }
 
            constexpr suspend_always final_suspend() const noexcept { return {}; }
 
            template<typename U = T, std::enable_if_t<!std::is_rvalue_reference<U>::value, int> = 0>
            Promise& yield_value(std::remove_reference_t<T>& value) noexcept {
                current = std::addressof(value);
                return *this;
            }
 
            Promise& yield_value(std::remove_reference_t<T>&& value) noexcept {
                current = std::addressof(value);
                return *this;
            }
 
            void unhandled_exception() noexcept {
                exception = std::current_exception(); // NOLINT
                current.reset();
 
                // case finished:
                //    Activate the iterator anyway.
                //    It's not a good pattern but this point is the appropriate
                //    for the iterator to notice and stop the loop
                return await_resume();
            }
 
            void return_void() noexcept {
                current.reset();
 
                // case finished:
                //    Activate the iterator anyway.
                //    It's not a good pattern but this point is the appropriate
                //    for the iterator to notice and stop the loop
                return await_resume();
            }
 
            bool await_ready() const noexcept {
                // Never suspend if there is a waiting iterator.
                // It will be resumed in `await_resume` function.
                //
                // !!! Using relaxed order here needs more verification !!!
                //
                return task.address() != nullptr;
            }
 
            void await_suspend(const AsyncCoroutineHandle handle) noexcept {
                UniqueLock<Mutex> lock(mutex);
                // iterator will reactivate this
                task = handle;
            }
 
            void await_resume() noexcept {
                AsyncCoroutineHandle coroutine = nullptr;
                {
                    UniqueLock<Mutex> lock(mutex);
                    coroutine = task;
                    task = nullptr;
                }
 
                // Resume if and only if  there is a waiting work
                //
                if(coroutine) {
                    coroutine.resume();
                }
            }
 
            Reference value() const noexcept { return **current; }
 
            void rethrow() {
                if(exception) {
                    CE_UNLIKELY { std::rethrow_exception(exception); }
                }
            }
        };
 
        class Iterator final {
        private:
            Promise* mPromise = nullptr;
 
        public:
            Iterator() noexcept : mPromise(nullptr) {}
 
            explicit Iterator(std::nullptr_t) noexcept : mPromise(nullptr) {}
 
            explicit Iterator(const AsyncCoroutineHandle handle) noexcept : mPromise(nullptr) {
                auto& p = CoroutineHandle::from_address(handle.address()).promise();
                mPromise = std::addressof(p);
            }
 
        public: // Iterator concept
            using iterator_category = std::input_iterator_tag;
            using difference_type = std::ptrdiff_t;
            using value_type = T;
            using reference = T const&;
            using pointer = T const*;
 
            [[nodiscard]] bool operator==(const Iterator& rhs) const noexcept { return this->mPromise == rhs.mPromise; }
 
            [[nodiscard]] bool operator!=(const Iterator& rhs) const noexcept { return !(*this == rhs); }
 
            Iterator operator++(int) = delete; // NOLINT
 
            Iterator& operator++() {
                // reset and advance
                mPromise->current = nullptr;
 
                // iterator resumes promise if it is suspended
                mPromise->await_resume();
                return await_resume();
            }
 
            [[nodiscard]] reference operator*() noexcept { return mPromise->value(); }
 
            [[nodiscard]] reference operator*() const noexcept { return mPromise->value(); }
 
            [[nodiscard]] pointer operator->() noexcept { return &mPromise->value(); }
 
            [[nodiscard]] pointer operator->() const noexcept { return &mPromise->value(); }
 
            [[nodiscard]] bool await_ready() const noexcept {
                // case finished:
                //    Must advance because there is nothing to resume this
                //    iterator
                if(mPromise == nullptr) {
                    return true;
                }
 
                // case yield:
                //    Continue the loop
                return mPromise->current != nullptr;
            }
 
            void await_suspend(AsyncCoroutineHandle rh) noexcept {
                // case empty:
                //   Promise suspended for some reason. Wait for it to yield
                //   Expect promise to resume this iterator appropriately
                //
                UniqueLock<Mutex> lock(mPromise->mutex);
                mPromise->task = rh;
            }
 
            Iterator& await_resume() {
                if(mPromise) {
                    mPromise->rethrow();
 
                    // case finished:
                    //    There is nothing we can do in this iterator.
                    //    We have meet the end condition of `for-co_await`
                    if(mPromise->current == std::nullopt) {
                        mPromise = nullptr;
                    }
                }
                return *this;
            }
        };
    };
 
} // namespace CeresEngine