第27课 “共享状态”及其管理者（std::future/std::shared_future）

// CLASS TEMPLATE _Associated_state
template <class _Ty>
class _Associated_state { // class for managing associated synchronous state
public:
    using _State_type = _Ty;
    using _Mydel      = _Deleter_base<_Ty>;

    _Associated_state(_Mydel* _Dp = nullptr)
        : _Refs(1), // non-atomic initialization
          _Exception(), _Retrieved(false), _Ready(false), _Ready_at_thread_exit(false), _Has_stored_result(false),
          _Running(false), _Deleter(_Dp) { // construct
        // TODO: _Associated_state ctor assumes _Ty is default constructible
    }

    virtual ~_Associated_state() noexcept { // 析构函数：注意并不会阻塞
        if (_Has_stored_result && !_Ready) { // registered for release at thread exit
            _Cond._Unregister(_Mtx);
        }
    }

    void _Retain() { // 增加引用计数
        _MT_INCR(_Refs);
    }

    void _Release() { // 减少引用计数，等于0时delete this
        if (_MT_DECR(_Refs) == 0) {
            _Delete_this();
        }
    }

private:
    _Atomic_counter_t _Refs;

public:
    virtual void _Wait() { // wait for signal
        unique_lock<mutex> _Lock(_Mtx);
        _Maybe_run_deferred_function(_Lock);
        while (!_Ready) {
            _Cond.wait(_Lock);
        }
    }

    struct _Test_ready { // _Associated_state包装类
        _Test_ready(const _Associated_state* _St) : _State(_St) { // construct from associated state
        }

        bool operator()() const { // 判断“共享状态”是否就绪
            return _State->_Ready != 0;
        }
        const _Associated_state* _State;
    };

    template <class _Rep, class _Per>
    future_status _Wait_for(const chrono::duration<_Rep, _Per>& _Rel_time) { // wait for duration
        unique_lock<mutex> _Lock(_Mtx);
        if (_Has_deferred_function()) {
            return future_status::deferred; //如果是延迟任务，调用waitfor将返回deferred，而不是future_status::ready!
        }

        if (_Cond.wait_for(_Lock, _Rel_time, _Test_ready(this))) {
            return future_status::ready; //返回future_status::ready
        }

        return future_status::timeout; //返回超时
    }

    template <class _Clock, class _Dur>
    future_status _Wait_until(const chrono::time_point<_Clock, _Dur>& _Abs_time) { // wait until time point
        unique_lock<mutex> _Lock(_Mtx);
        if (_Has_deferred_function()) {
            return future_status::deferred;
        }

        if (_Cond.wait_until(_Lock, _Abs_time, _Test_ready(this))) {
            return future_status::ready;
        }

        return future_status::timeout;
    }

    virtual _Ty& _Get_value(bool _Get_only_once) { // return the stored result or throw stored exception
        unique_lock<mutex> _Lock(_Mtx);
        if (_Get_only_once && _Retrieved) { //_Get_only_once：true表示_Get_value只能调用一次，false表示可重复调用
            _Throw_future_error(make_error_code(future_errc::future_already_retrieved));
        }

        if (_Exception) {
            _Rethrow_future_exception(_Exception);
        }

        _Retrieved = true; //标记_Get_value()函数己被调用过
        _Maybe_run_deferred_function(_Lock);
        while (!_Ready) { //如果任务结束，则不再等待。
            _Cond.wait(_Lock);
        }

        if (_Exception) {
            _Rethrow_future_exception(_Exception);
        }

        return _Result;
    }

    void _Set_value(const _Ty& _Val, bool _At_thread_exit) { // store a result
        unique_lock<mutex> _Lock(_Mtx);
        _Set_value_raw(_Val, &_Lock, _At_thread_exit);
    }

    void _Set_value_raw(const _Ty& _Val, unique_lock<mutex>* _Lock,
        bool _At_thread_exit) { // store a result while inside a locked block
        if (_Has_stored_result) {
            _Throw_future_error(make_error_code(future_errc::promise_already_satisfied));
        }

        _Result = _Val;
        _Do_notify(_Lock, _At_thread_exit);
    }

    void _Set_value(_Ty&& _Val, bool _At_thread_exit) { // store a result
        unique_lock<mutex> _Lock(_Mtx);
        _Set_value_raw(_STD forward<_Ty>(_Val), &_Lock, _At_thread_exit);
    }

    void _Set_value_raw(_Ty&& _Val, unique_lock<mutex>* _Lock,
        bool _At_thread_exit) { // store a result while inside a locked block
        if (_Has_stored_result) {
            _Throw_future_error(make_error_code(future_errc::promise_already_satisfied));
        }

        _Result = _STD forward<_Ty>(_Val);
        _Do_notify(_Lock, _At_thread_exit);
    }

    void _Set_value(bool _At_thread_exit) { // store a (void) result
        unique_lock<mutex> _Lock(_Mtx);
        _Set_value_raw(&_Lock, _At_thread_exit);
    }

    void _Set_value_raw(
        unique_lock<mutex>* _Lock, bool _At_thread_exit) { // store a (void) result while inside a locked block
        if (_Has_stored_result) {
            _Throw_future_error(make_error_code(future_errc::promise_already_satisfied));
        }

        _Do_notify(_Lock, _At_thread_exit);
    }

    void _Set_exception(exception_ptr _Exc, bool _At_thread_exit) { // store a result
        unique_lock<mutex> _Lock(_Mtx);
        _Set_exception_raw(_Exc, &_Lock, _At_thread_exit);
    }

    void _Set_exception_raw(exception_ptr _Exc, unique_lock<mutex>* _Lock,
        bool _At_thread_exit) { // store a result while inside a locked block
        if (_Has_stored_result) {
            _Throw_future_error(make_error_code(future_errc::promise_already_satisfied));
        }

        _Exception = _Exc;
        _Do_notify(_Lock, _At_thread_exit);
    }

    bool _Is_ready() const { // return ready status
        return _Ready != 0;
    }

    bool _Is_ready_at_thread_exit() const { // return ready at thread exit status
        return _Ready_at_thread_exit;
    }

    bool _Already_has_stored_result() const { // return presence of stored result
        return _Has_stored_result;
    }

    bool _Already_retrieved() const { // return retrieved status
        return _Retrieved;
    }

    void _Abandon() { // abandon shared state
        unique_lock<mutex> _Lock(_Mtx);
        if (!_Has_stored_result) { // queue exception
            future_error _Fut(make_error_code(future_errc::broken_promise));
            _Set_exception_raw(_STD make_exception_ptr(_Fut), &_Lock, false);
        }
    }

protected:
    void _Make_ready_at_thread_exit() { // set ready status at thread exit
        if (_Ready_at_thread_exit) {
            _Ready = true;
        }
    }

    void _Maybe_run_deferred_function(unique_lock<mutex>& _Lock) {
        if (!_Running) { //延迟任务默认值为false，只能调用该函数后，才会变为true
            _Running = true;
            _Run_deferred_function(_Lock); //执行延迟任务
        }
    }

public:
    _Ty _Result;
    exception_ptr _Exception;
    mutex _Mtx;
    condition_variable _Cond;
    bool _Retrieved; //用于标记_Get_value函数是否己被调用过，true表示己调用过，false为未调用过
    int _Ready; //是否处于就绪状态，用于唤醒等待线程。（有些任务做完线程就被置为就绪状态，而有些任务要等线程退出时才置就绪）
    bool _Ready_at_thread_exit;//是否在线程退出时才设为就绪状态
    bool _Has_stored_result; //调用_Do_notify时表示结果己计算出来，该值被置为true。
    bool _Running; //用于标识线程是否正在运行（异步任务默认值为true，延迟任务默认值为false）
private:
    virtual bool _Has_deferred_function() const noexcept { // 被_Deferred_async_state子类override
        return false;
    }

    virtual void _Run_deferred_function(unique_lock<mutex>&) { // do nothing
    }

    virtual void _Do_notify(unique_lock<mutex>* _Lock, bool _At_thread_exit) { // 通知等待线程。
        _Has_stored_result = true; 
        if (_At_thread_exit) { //线程退出时，才唤醒等待线程
            _Cond._Register(*_Lock, &_Ready);
        } else { // 立即唤醒等待线程
            _Ready = true;
            _Cond.notify_all();
        }
    }

    void _Delete_this() { // delete this object
        if (_Deleter) {
            _Deleter->_Delete(this);
        } else {
            delete this; //删除自身
        }
    }

    _Mydel* _Deleter;

public:
    _Associated_state(const _Associated_state&) = delete;  //不可复制
    _Associated_state& operator=(const _Associated_state&) = delete; //不可复制赋值
};

// CLASS TEMPLATE _Packaged_state
template <class>
class _Packaged_state;

template <class _Ret,
    class... _ArgTypes>
class _Packaged_state<_Ret(_ArgTypes...)>
    : public _Associated_state<_Ret> { //为packaged_task准备的”共享状态“
public:
    using _Mybase = _Associated_state<_Ret>;
    using _Mydel  = typename _Mybase::_Mydel;

    template <class _Fty2>
    _Packaged_state(const _Fty2& _Fnarg) : _Fn(_Fnarg) { // construct from function object
    }

#if _HAS_FUNCTION_ALLOCATOR_SUPPORT
    template <class _Fty2, class _Alloc>
    _Packaged_state(const _Fty2& _Fnarg, const _Alloc& _Al, _Mydel* _Dp)
        : _Mybase(_Dp), _Fn(allocator_arg, _Al, _Fnarg) { // construct from function object and allocator
    }
#endif // _HAS_FUNCTION_ALLOCATOR_SUPPORT

    template <class _Fty2>
    _Packaged_state(_Fty2&& _Fnarg) : _Fn(_STD forward<_Fty2>(_Fnarg)) { // construct from rvalue function object
    }

#if _HAS_FUNCTION_ALLOCATOR_SUPPORT
    template <class _Fty2, class _Alloc>
    _Packaged_state(_Fty2&& _Fnarg, const _Alloc& _Al, _Mydel* _Dp)
        : _Mybase(_Dp), _Fn(allocator_arg, _Al,
                            _STD forward<_Fty2>(_Fnarg)) { // construct from rvalue function object and allocator
    }
#endif // _HAS_FUNCTION_ALLOCATOR_SUPPORT

    //提供给Provider使用的，provider会通过set_value_at_thread_exit调用该函数来实现线程退出时唤醒等待线程。
    void _Call_deferred(_ArgTypes... _Args) { //这类延迟函数，在线程退出时将任务设为就绪状态，才会唤醒其他线程。。
        _TRY_BEGIN
        // call function object and catch exceptions
        this->_Set_value(_Fn(_STD forward<_ArgTypes>(_Args)...), true); //执行_Fn函数，并将返回值提供给_Set_value函数。t
        _CATCH_ALL                                                      //true表示线程退出时才唤醒等待线程
        // function object threw exception; record result
        this->_Set_exception(_STD current_exception(), true);
        _CATCH_END
    }

    //立即调用线程函数，执行完立即唤醒等待线程。比如std::async不管是同步或异步，都是在执行完立即唤醒等待线程。
    void _Call_immediate(_ArgTypes... _Args) {
        _TRY_BEGIN
        // call function object and catch exceptions
        this->_Set_value(_Fn(_STD forward<_ArgTypes>(_Args)...), false);//立即调用函数对象，false表示任务做完立即唤醒等待线程
        _CATCH_ALL
        // function object threw exception; record result
        this->_Set_exception(_STD current_exception(), false);
        _CATCH_END
    }

    const function<_Ret(_ArgTypes...)>& _Get_fn() { // return stored function object
        return _Fn;
    }

private:
    function<_Ret(_ArgTypes...)> _Fn;
};

// CLASS TEMPLATE _Deferred_async_state
template <class _Rx>
class _Deferred_async_state : public _Packaged_state<_Rx()> { //std::async创建的同步”共享状态“
public:
    template <class _Fty2>
    _Deferred_async_state(const _Fty2& _Fnarg) : _Packaged_state<_Rx()>(_Fnarg) { // construct from function object
    }

    template <class _Fty2>
    _Deferred_async_state(_Fty2&& _Fnarg)
        : _Packaged_state<_Rx()>(_STD forward<_Fty2>(_Fnarg)) { // construct from rvalue function object
    }

private:
    virtual bool _Has_deferred_function() const
        noexcept { // this function is considered to be deferred until it's invoked
        return !this->_Running; //如果任务己被执行过，就不在是视为延迟任务
    }

    virtual void _Run_deferred_function(unique_lock<mutex>& _Lock) { // run the deferred function
        _Lock.unlock();
        _Packaged_state<_Rx()>::_Call_immediate(); //注意，这里不是调用_Call::deferred()!!!
        _Lock.lock();
    }
};

// CLASS TEMPLATE _Task_async_state
template <class _Rx>
class _Task_async_state : public _Packaged_state<_Rx()> { //std::async创建的异步”共享状态“ 
public:
    using _Mybase     = _Packaged_state<_Rx()>;
    using _State_type = typename _Mybase::_State_type;

    template <class _Fty2>
    _Task_async_state(_Fty2&& _Fnarg) : _Mybase(_STD forward<_Fty2>(_Fnarg)) { // construct from rvalue function object
        _Task = ::Concurrency::create_task([this]() { // do it now
            this->_Call_immediate();
        });

        this->_Running = true; //异步任务，线程一启动就处于running状态。
    }

    virtual ~_Task_async_state() noexcept { // destroy
        _Wait();   //异步“共享状态”对象析构时，会被阻塞！！！
    }

    virtual void _Wait() { // wait for completion
        _Task.wait(); //重写_Wait()。注意，这里调用的是线程级别的wait，相当于对底层线程实施一次隐式join()。
    }

    virtual _State_type& _Get_value(bool _Get_only_once) { // return the stored result or throw stored exception
        _Task.wait(); //异步“共享状态”对象，在调用Get_value时，也会被阻塞！
        return _Mybase::_Get_value(_Get_only_once);
    }

private:
    ::Concurrency::task<void> _Task;
};

// CLASS TEMPLATE _State_manager
template <class _Ty>
class _State_manager { //“共享状态”管理器
public:
    _State_manager() : _Assoc_state(nullptr) { // construct with no associated asynchronous state object
        _Get_only_once = false;  //注意，默认get()函数是可多次调用的
    }

    _State_manager(_Associated_state<_Ty>* _New_state, bool _Get_once)
        : _Assoc_state(_New_state) { // construct with _New_state
        _Get_only_once = _Get_once;
    }

    _State_manager(const _State_manager& _Other, bool _Get_once = false)
        : _Assoc_state(nullptr) { // construct from _Other
        _Copy_from(_Other);
        _Get_only_once = _Get_once;
    }

    _State_manager(_State_manager&& _Other, bool _Get_once = false)
        : _Assoc_state(nullptr) { // construct from rvalue _Other
        _Move_from(_Other);
        _Get_only_once = _Get_once;
    }

    ~_State_manager() noexcept { // destroy
        if (_Assoc_state != nullptr) {
            _Assoc_state->_Release(); //_State_manager对象析构时，会同时将管理的“共享状态”的引用计数自减1
        }
    }

    _State_manager& operator=(const _State_manager& _Other) { // assign from _Other
        _Copy_from(_Other);
        return *this;
    }

    _State_manager& operator=(_State_manager&& _Other) { // assign from rvalue _Other
        _Move_from(_Other);
        return *this;
    }

     //检查当前的 std::future 对象是否有效，即释放与某个共享状态相关联
    _NODISCARD bool valid() const noexcept {
        return _Assoc_state != nullptr && !(_Get_only_once && _Assoc_state->_Already_retrieved());
    }

    //等待与当前std::future 对象相关联的共享状态的标志变为 ready.
    void wait() const { // wait for signal
        if (!valid()) {
            _Throw_future_error(make_error_code(future_errc::no_state));
        }

        _Assoc_state->_Wait(); //等待条件变量
    }

    template <class _Rep, class _Per>
    future_status wait_for(const chrono::duration<_Rep, _Per>& _Rel_time) const { // wait for duration
        if (!valid()) {
            _Throw_future_error(make_error_code(future_errc::no_state));
        }

        return _Assoc_state->_Wait_for(_Rel_time);
    }

    template <class _Clock, class _Dur>
    future_status wait_until(const chrono::time_point<_Clock, _Dur>& _Abs_time) const { // wait until time point
        if (!valid()) {
            _Throw_future_error(make_error_code(future_errc::no_state));
        }

        return _Assoc_state->_Wait_until(_Abs_time);
    }

    _Ty& _Get_value() const { // return the stored result or throw stored exception
        if (!valid()) {
            _Throw_future_error(make_error_code(future_errc::no_state));
        }

        return _Assoc_state->_Get_value(_Get_only_once);
    }

    void _Set_value(const _Ty& _Val, bool _Defer) { // store a result
        if (!valid()) {
            _Throw_future_error(make_error_code(future_errc::no_state));
        }

        _Assoc_state->_Set_value(_Val, _Defer);
    }

    void _Set_value(_Ty&& _Val, bool _Defer) { // store a result
        if (!valid()) {
            _Throw_future_error(make_error_code(future_errc::no_state));
        }

        _Assoc_state->_Set_value(_STD forward<_Ty>(_Val), _Defer);
    }

    void _Abandon() { // abandon shared state
        if (_Assoc_state) {
            _Assoc_state->_Abandon();
        }
    }

    void _Set_exception(exception_ptr _Exc, bool _Defer) { // store a result
        if (!valid()) {
            _Throw_future_error(make_error_code(future_errc::no_state));
        }

        _Assoc_state->_Set_exception(_Exc, _Defer);
    }

    void _Swap(_State_manager& _Other) { // exchange with _Other
        _STD swap(_Assoc_state, _Other._Assoc_state);
    }

    _Associated_state<_Ty>* _Ptr() const { // return pointer to stored associated asynchronous state object
        return _Assoc_state;
    }

    void _Copy_from(const _State_manager& _Other) { // copy stored associated asynchronous state object from _Other
        if (this != _STD addressof(_Other)) { // different, copy
            if (_Assoc_state) {
                _Assoc_state->_Release();
            }

            if (_Other._Assoc_state == nullptr) {
                _Assoc_state = nullptr;
            } else { // do the copy
                _Other._Assoc_state->_Retain();
                _Assoc_state   = _Other._Assoc_state;
                _Get_only_once = _Other._Get_only_once;
            }
        }
    }

    void _Move_from(_State_manager& _Other) { // move stored associated asynchronous state object from _Other
        if (this != _STD addressof(_Other)) { // different, move
            if (_Assoc_state) {
                _Assoc_state->_Release();
            }

            _Assoc_state        = _Other._Assoc_state;
            _Other._Assoc_state = nullptr;
            _Get_only_once      = _Other._Get_only_once;
        }
    }

    bool _Is_ready() const { // return ready status
        return _Assoc_state && _Assoc_state->_Is_ready();
    }

    bool _Is_ready_at_thread_exit() const { // return ready at thread exit status
        return _Assoc_state && _Assoc_state->_Is_ready_at_thread_exit();
    }

private:
    _Associated_state<_Ty>* _Assoc_state;
    bool _Get_only_once;
};

// CLASS TEMPLATE future
template <class _Ty>
class shared_future;

template <class _Ty>
class future : public _State_manager<_Ty> { // class that defines a non-copyable asynchronous return object
                                            // that holds a value
    using _Mybase = _State_manager<_Ty>;

public:
    future() noexcept { // construct
    }

    future(future&& _Other) noexcept : _Mybase(_STD move(_Other), true) { // true表示get只能被调用一次。
    }

    future& operator=(future&& _Right) noexcept { // assign from rvalue future object
        _Mybase::operator=(_STD move(_Right));
        return *this;
    }

    future(const _Mybase& _State, _Nil) : _Mybase(_State, true) { // construct from associated asynchronous state object
    }

    ~future() noexcept { // destroy
    }

    _Ty get() { // block until ready then return the stored result or
                // throw the stored exception
        future _Local{_STD move(*this)}; //注意，移动操作，将使调用get()函数后，future将失去与“共享状态”的关联，valid()变为无效。
        return _STD move(_Local._Get_value());
    }

    _NODISCARD shared_future<_Ty> share() noexcept { // return state as shared_future
        return shared_future<_Ty>(_STD move(*this));
    }

    future(const future&) = delete;
    future& operator=(const future&) = delete;
};

// CLASS TEMPLATE shared_future
template <class _Ty>
class shared_future : public _State_manager<_Ty> { // class that defines a copyable asynchronous return object
                                                   // that holds a value
    using _Mybase = _State_manager<_Ty>;

public:
    shared_future() noexcept { // _Mybase中将_Get_Only_once默认值设为false，表示get()可多次调用。
    }

    shared_future(const shared_future& _Other) noexcept : _Mybase(_Other) { //拷贝构造
    }

    shared_future& operator=(const shared_future& _Right) noexcept { // 拷贝赋值

        _Mybase::operator=(_Right);
        return *this;
    }

    shared_future(future<_Ty>&& _Other) noexcept
        : _Mybase(_STD forward<_Mybase>(_Other)) { // 移动构造
    }

    shared_future(shared_future&& _Other) noexcept
        : _Mybase(_STD move(_Other)) { // construct from rvalue shared_future object
    }

    shared_future& operator=(shared_future&& _Right) noexcept { // assign from shared_future rvalue object

        _Mybase::operator=(_STD move(_Right));
        return *this;
    }

    ~shared_future() noexcept { // destroy
    }

    const _Ty& get() const { // 阻塞，直到任务就绪。
        return this->_Get_value(); //返回值是个只读对象！
    }
};