JobQueue.h

#pragma once
 
#include <xrpl/basics/LocalValue.h>
#include <xrpl/core/ClosureCounter.h>
#include <xrpl/core/JobTypeData.h>
#include <xrpl/core/JobTypes.h>
#include <xrpl/core/detail/Workers.h>
#include <xrpl/json/json_value.h>
 
// Include only the specific Boost.Coroutine2 headers actually used here.
// Avoid `boost/coroutine2/all.hpp` because it transitively pulls in
// `boost/context/pooled_fixedsize_stack.hpp`, whose `.malloc()` / `.free()`
// member calls on `boost::pool` collide with MSVC's `_CRTDBG_MAP_ALLOC` macros
// in Debug builds (see cmake/XrplCompiler.cmake).
#include <boost/context/protected_fixedsize_stack.hpp>
#include <boost/coroutine2/coroutine.hpp>
 
#include <set>
 
namespace xrpl {
 
namespace perf {
class PerfLog;
}  // namespace perf
 
class Logs;
struct CoroCreateT
{
    explicit CoroCreateT() = default;
};

class JobQueue : private Workers::Callback
{
public:
    class Coro : public std::enable_shared_from_this<Coro>
    {
    private:
        detail::LocalValues lvs_;
        JobQueue& jq_;
        JobType type_;
        std::string name_;
        bool running_{false};
        std::mutex mutex_;
        std::mutex mutexRun_;
        std::condition_variable cv_;
        boost::coroutines2::coroutine<void>::push_type* yield_{};
        boost::coroutines2::coroutine<void>::pull_type coro_;
#ifndef NDEBUG
        bool finished_ = false;
#endif
 
    public:
        template <class F>
        Coro(CoroCreateT, JobQueue&, JobType, std::string, F&&);
 
        // Not copy-constructible or assignable
        Coro(Coro const&) = delete;
        Coro&
        operator=(Coro const&) = delete;
 
        ~Coro();

        void
        yield() const;

        bool
        post();

        void
        resume();

        bool
        runnable() const;

        void
        expectEarlyExit();

        void
        join();
    };
 
    using JobFunction = std::function<void()>;
 
    JobQueue(
        int threadCount,
        beast::insight::Collector::ptr const& collector,
        beast::Journal journal,
        Logs& logs,
        perf::PerfLog& perfLog);
    ~JobQueue() override;

    template <
        typename JobHandler,
        typename = std::enable_if_t<std::is_same_v<decltype(std::declval<JobHandler&&>()()), void>>>
    bool
    addJob(JobType type, std::string const& name, JobHandler&& jobHandler)
    {
        if (auto optionalCountedJob = jobCounter_.wrap(std::forward<JobHandler>(jobHandler)))
        {
            return addRefCountedJob(type, name, std::move(*optionalCountedJob));
        }
        return false;
    }

    template <class F>
    std::shared_ptr<Coro>
    postCoro(JobType t, std::string const& name, F&& f);

    int
    getJobCount(JobType t) const;

    int
    getJobCountTotal(JobType t) const;

    int
    getJobCountGE(JobType t) const;

    std::unique_ptr<LoadEvent>
    makeLoadEvent(JobType t, std::string const& name);

    void
    addLoadEvents(JobType t, int count, std::chrono::milliseconds elapsed);
 
    // Cannot be const because LoadMonitor has no const methods.
    bool
    isOverloaded();
 
    // Cannot be const because LoadMonitor has no const methods.
    json::Value
    getJson(int c = 0);

    void
    rendezvous();
 
    void
    stop();
 
    bool
    isStopping() const
    {
        return stopping_;
    }
 
    // We may be able to move away from this, but we can keep it during the
    // transition.
    bool
    isStopped() const;
 
private:
    friend class Coro;
 
    using JobDataMap = std::map<JobType, JobTypeData>;
 
    beast::Journal journal_;
    mutable std::mutex mutex_;
    std::uint64_t lastJob_{0};
    std::set<Job> jobSet_;
    JobCounter jobCounter_;
    std::atomic_bool stopping_{false};
    std::atomic_bool stopped_{false};
    JobDataMap jobData_;
    JobTypeData invalidJobData_;
 
    // The number of jobs currently in processTask()
    int processCount_{0};
 
    // The number of suspended coroutines
    int nSuspend_ = 0;
 
    Workers workers_;
 
    // Statistics tracking
    perf::PerfLog& perfLog_;
    beast::insight::Collector::ptr collector_;
    beast::insight::Gauge jobCount_;
    beast::insight::Hook hook_;
 
    std::condition_variable cv_;
 
    void
    collect();
    JobTypeData&
    getJobTypeData(JobType type);
 
    // Adds a reference counted job to the JobQueue.
    //
    //    param type The type of job.
    //    param name Name of the job.
    //    param func std::function with signature void (Job&).  Called when the
    //    job is executed.
    //
    //    return true if func added to queue.
    bool
    addRefCountedJob(JobType type, std::string const& name, JobFunction const& func);
 
    // Returns the next Job we should run now.
    //
    // RunnableJob:
    //  A Job in the JobSet whose slots count for its type is greater than zero.
    //
    // Pre-conditions:
    //  jobSet_ must not be empty.
    //  jobSet_ holds at least one RunnableJob
    //
    // Post-conditions:
    //  job is a valid Job object.
    //  job is removed from jobQueue_.
    //  Waiting job count of its type is decremented
    //  Running job count of its type is incremented
    //
    // Invariants:
    //  The calling thread owns the JobLock
    void
    getNextJob(Job& job);
 
    // Indicates that a running Job has completed its task.
    //
    // Pre-conditions:
    //  Job must not exist in jobSet_.
    //  The JobType must not be invalid.
    //
    // Post-conditions:
    //  The running count of that JobType is decremented
    //  A new task is signaled if there are more waiting Jobs than the limit, if
    //  any.
    //
    // Invariants:
    //  <none>
    void
    finishJob(JobType type);
 
    // Runs the next appropriate waiting Job.
    //
    // Pre-conditions:
    //  A RunnableJob must exist in the JobSet
    //
    // Post-conditions:
    //  The chosen RunnableJob will have Job::doJob() called.
    //
    // Invariants:
    //  <none>
    void
    processTask(int instance) override;
 
    // Returns the limit of running jobs for the given job type.
    // For jobs with no limit, we return the largest int. Hopefully that
    // will be enough.
    static int
    getJobLimit(JobType type);
};
 
/*
    An RPC command is received and is handled via ServerHandler(HTTP) or
    Handler(websocket), depending on the connection type. The handler then calls
    the JobQueue::postCoro() method to create a coroutine and run it at a later
    point. This frees up the handler thread and allows it to continue handling
    other requests while the RPC command completes its work asynchronously.
 
    postCoro() creates a Coro object. When the Coro ctor is called, and its
    coro_ member is initialized (a boost::coroutines::pull_type), execution
    automatically passes to the coroutine, which we don't want at this point,
    since we are still in the handler thread context. It's important to note
   here that construction of a boost pull_type automatically passes execution to
   the coroutine. A pull_type object automatically generates a push_type that is
    passed as a parameter (do_yield) in the signature of the function the
    pull_type was created with. This function is immediately called during coro_
    construction and within it, Coro::yield_ is assigned the push_type
    parameter (do_yield) address and called (yield()) so we can return execution
    back to the caller's stack.
 
    postCoro() then calls Coro::post(), which schedules a job on the job
    queue to continue execution of the coroutine in a JobQueue worker thread at
    some later time. When the job runs, we lock on the Coro::mutex_ and call
    coro_ which continues where we had left off. Since we the last thing we did
    in coro_ was call yield(), the next thing we continue with is calling the
    function param f, that was passed into Coro ctor. It is within this
    function body that the caller specifies what he would like to do while
    running in the coroutine and allow them to suspend and resume execution.
    A task that relies on other events to complete, such as path finding, calls
    Coro::yield() to suspend its execution while waiting on those events to
    complete and continue when signaled via the Coro::post() method.
 
    There is a potential race condition that exists here where post() can get
    called before yield() after f is called. Technically the problem only occurs
    if the job that post() scheduled is executed before yield() is called.
    If the post() job were to be executed before yield(), undefined behavior
    would occur. The lock ensures that coro_ is not called again until we exit
    the coroutine. At which point a scheduled resume() job waiting on the lock
    would gain entry. resume() checks if the coroutine has already completed
    (coro_ converts to false) and, if so, skips invoking operator() since
    calling operator() on a completed boost::coroutine2 pull_type is undefined
    behavior.
 
    The race condition occurs as follows:
 
        1- The coroutine is running.
        2- The coroutine is about to suspend, but before it can do so, it must
            arrange for some event to wake it up.
        3- The coroutine arranges for some event to wake it up.
        4- Before the coroutine can suspend, that event occurs and the
   resumption of the coroutine is scheduled on the job queue. 5- Again, before
   the coroutine can suspend, the resumption of the coroutine is dispatched. 6-
   Again, before the coroutine can suspend, the resumption code runs the
            coroutine.
        The coroutine is now running in two threads.
 
        The lock prevents this from happening as step 6 will block until the
            lock is released which only happens after the coroutine completes.
*/
 
}  // namespace xrpl
 
#include <xrpl/core/Coro.ipp>
 
namespace xrpl {
 
template <class F>
std::shared_ptr<JobQueue::Coro>
JobQueue::postCoro(JobType t, std::string const& name, F&& f)
{
    /*  First param is a detail type to make construction private.
        Last param is the function the coroutine runs. Signature of
        void(std::shared_ptr<Coro>).
    */
    auto coro = std::make_shared<Coro>(CoroCreateT{}, *this, t, name, std::forward<F>(f));
    if (!coro->post())
    {
        // The Coro was not successfully posted.  Disable it so it's destructor
        // can run with no negative side effects.  Then destroy it.
        coro->expectEarlyExit();
        coro.reset();
    }
    return coro;
}
 
}  // namespace xrpl