gate.hh

/*
 * This file is open source software, licensed to you under the terms
 * of the Apache License, Version 2.0 (the "License").  See the NOTICE file
 * distributed with this work for additional information regarding copyright
 * ownership.  You may not use this file except in compliance with the License.
 *
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
/*
 * Copyright 2014 Cloudius Systems
 */
 
#pragma once
 
#ifndef SEASTAR_MODULE
#include <boost/intrusive/list.hpp>
 
#include <seastar/core/future.hh>
#include <seastar/util/assert.hh>
#include <seastar/util/std-compat.hh>
#include <seastar/util/modules.hh>
#include <cassert>
#include <exception>
#include <optional>
#include <utility>
#endif
 
#ifdef SEASTAR_DEBUG
#define SEASTAR_GATE_HOLDER_DEBUG
#endif
 
namespace seastar {
 
 
SEASTAR_MODULE_EXPORT
class gate_closed_exception : public std::exception {
public:
    virtual const char* what() const noexcept override {
        return "gate closed";
    }
};
 
SEASTAR_MODULE_EXPORT
class named_gate_closed_exception : public gate_closed_exception {
    static constexpr const char* _default_what = "named gate closed";
    sstring _what;
public:
    named_gate_closed_exception(const sstring& name) noexcept : gate_closed_exception() {
        if (!name.empty()) {
            try {
                _what = fmt::format("{} gate closed", name);
            } catch (...) {
                // Ignore
            }
        }
    }
    virtual const char* what() const noexcept override {
        return _what.empty() ? _default_what : _what.c_str();
    }
};
 
SEASTAR_MODULE_EXPORT
class gate {
    size_t _count = 0;
    std::optional<promise<>> _stopped;
 
#ifdef SEASTAR_GATE_HOLDER_DEBUG
    void assert_not_held_when_moved() const noexcept;
    void assert_not_held_when_destroyed() const noexcept;
#else   // SEASTAR_GATE_HOLDER_DEBUG
    void assert_not_held_when_moved() const noexcept {}
    void assert_not_held_when_destroyed() const noexcept {}
#endif  // SEASTAR_GATE_HOLDER_DEBUG
 
public:
    // Implemented to force noexcept due to boost:intrusive::list
    gate() noexcept {};
    gate(const gate&) = delete;
    gate(gate&& x) noexcept
        : _count(std::exchange(x._count, 0)), _stopped(std::exchange(x._stopped, std::nullopt)) {
        x.assert_not_held_when_moved();
    }
    gate& operator=(gate&& x) noexcept {
        if (this != &x) {
            SEASTAR_ASSERT(!_count && "gate reassigned with outstanding requests");
            x.assert_not_held_when_moved();
            _count = std::exchange(x._count, 0);
            _stopped = std::exchange(x._stopped, std::nullopt);
        }
        return *this;
    }
    ~gate() {
        SEASTAR_ASSERT(!_count && "gate destroyed with outstanding requests");
        assert_not_held_when_destroyed();
    }
    bool try_enter() noexcept {
        bool opened = !_stopped;
        if (opened) {
            ++_count;
        }
        return opened;
    }
    void enter() {
        if (!try_enter()) {
            throw_closed_exception();
        }
    }
    void leave() noexcept {
        --_count;
        if (!_count && _stopped) {
            _stopped->set_value();
        }
    }
    void check() const {
        if (_stopped) {
            throw_closed_exception();
        }
    }
    future<> close() noexcept {
        SEASTAR_ASSERT(!_stopped && "seastar::gate::close() cannot be called more than once");
        _stopped = std::make_optional(promise<>());
        if (!_count) {
            _stopped->set_value();
        }
        return _stopped->get_future();
    }
 
    size_t get_count() const noexcept {
        return _count;
    }
 
    bool is_closed() const noexcept {
        return bool(_stopped);
    }
 
    class holder {
        gate* _g;
#ifdef SEASTAR_GATE_HOLDER_DEBUG
        using member_hook_t = boost::intrusive::list_member_hook<boost::intrusive::link_mode<boost::intrusive::auto_unlink>>;
        member_hook_t _link;
 
        void debug_hold_gate() noexcept {
            if (_g) {
                _g->_holders.push_back(*this);
            }
        }
 
        void debug_release_gate() noexcept {
            _link.unlink();
        }
#else   // SEASTAR_GATE_HOLDER_DEBUG
        void debug_hold_gate() noexcept {}
        void debug_release_gate() noexcept {}
#endif  // SEASTAR_GATE_HOLDER_DEBUG
 
        // release the holder from the gate without leaving it.
        // used for release and move.
        gate* release_gate() noexcept {
            auto* g = std::exchange(_g, nullptr);
            if (g) {
                debug_release_gate();
            }
            return g;
        }
 
        friend class gate;
    public:
        holder() noexcept : _g(nullptr) { }
 
        explicit holder(gate& g) : _g(&g) {
            _g->enter();
            debug_hold_gate();
        }
 
        holder(const holder& x) noexcept : _g(x._g) {
            if (_g) {
                _g->_count++;
                debug_hold_gate();
            }
        }
 
        holder(holder&& x) noexcept : _g(std::move(x).release_gate()) {
            debug_hold_gate();
        }
 
        ~holder() {
            release();
        }
 
        holder& operator=(const holder& x) noexcept {
            if (x._g != _g) {
                release();
                _g = x._g;
                if (_g) {
                    _g->_count++;
                    debug_hold_gate();
                }
            }
            return *this;
        }
 
        holder& operator=(holder&& x) noexcept {
            if (&x != this) {
                release();
                _g = std::move(x).release_gate();
                debug_hold_gate();
            }
            return *this;
        }
 
        void release() noexcept {
            if (auto g = release_gate()) {
                g->leave();
            }
        }
    };
 
    holder hold() {
        return holder(*this);
    }
 
    std::optional<holder> try_hold() noexcept {
        return is_closed() ? std::nullopt : std::make_optional<holder>(*this);
    }
 
protected:
    virtual std::exception_ptr make_closed_exception() const {
        return std::make_exception_ptr(gate_closed_exception{});
    }
 
    template <typename Func>
    friend auto try_with_gate(gate&, Func&&) noexcept;
private:
#ifdef SEASTAR_GATE_HOLDER_DEBUG
    using holders_list_t = boost::intrusive::list<holder,
        boost::intrusive::member_hook<holder, holder::member_hook_t, &holder::_link>,
        boost::intrusive::constant_time_size<false>>;
 
    holders_list_t _holders;
#endif  // SEASTAR_GATE_HOLDER_DEBUG
 
    [[noreturn]] void throw_closed_exception() const {
        std::rethrow_exception(make_closed_exception());
    }
};
 
#ifdef SEASTAR_GATE_HOLDER_DEBUG
SEASTAR_MODULE_EXPORT
inline void gate::assert_not_held_when_moved() const noexcept {
    SEASTAR_ASSERT(_holders.empty() && "gate moved with outstanding holders");
}
inline void gate::assert_not_held_when_destroyed() const noexcept {
    SEASTAR_ASSERT(_holders.empty() && "gate destroyed with outstanding holders");
}
#endif  // SEASTAR_GATE_HOLDER_DEBUG
 
class named_gate : public gate {
    sstring _name;
 
public:
    named_gate() = default;
    explicit named_gate(sstring name) noexcept
        : gate()
        , _name(std::move(name))
    {}
    named_gate(named_gate&&) = default;
    named_gate& operator=(named_gate&&) = default;
 
protected:
    virtual std::exception_ptr make_closed_exception() const override {
        return std::make_exception_ptr(named_gate_closed_exception(_name));
    }
};
 
namespace internal {
 
template <typename Func>
inline
auto
invoke_func_with_gate(gate::holder&& gh, Func&& func) noexcept {
    return futurize_invoke(std::forward<Func>(func)).finally([gh = std::forward<gate::holder>(gh)] {});
}
 
} // namespace internal
 
SEASTAR_MODULE_EXPORT
template <typename Func>
inline
auto
with_gate(gate& g, Func&& func) {
    return internal::invoke_func_with_gate(g.hold(), std::forward<Func>(func));
}
 
SEASTAR_MODULE_EXPORT
template <typename Func>
inline
auto
try_with_gate(gate& g, Func&& func) noexcept {
    if (g.is_closed()) {
        using futurator = futurize<std::invoke_result_t<Func>>;
        return futurator::make_exception_future(g.make_closed_exception());
    }
    return internal::invoke_func_with_gate(g.hold(), std::forward<Func>(func));
}
 
 
}