Merge branch 'release/luau-scripting' into viewer-lua-2237

6 files changed, 414 insertions, 1 deletions

diff --git a/indra/llcommon/CMakeLists.txt b/indra/llcommon/CMakeLists.txt
index 20670d7ebe..8472eac9f6 100644
--- a/indra/llcommon/CMakeLists.txt
+++ b/indra/llcommon/CMakeLists.txt
@@ -18,6 +18,7 @@ include(Tracy)
 set(llcommon_SOURCE_FILES
     apply.cpp
     commoncontrol.cpp
+    coro_scheduler.cpp
     hbxxh.cpp
     indra_constants.cpp
     lazyeventapi.cpp
@@ -112,6 +113,7 @@ set(llcommon_SOURCE_FILES
     lua_function.cpp
     lualistener.cpp
     threadpool.cpp
+    throttle.cpp
     u64.cpp
     workqueue.cpp
     StackWalker.cpp
@@ -125,6 +127,7 @@ set(llcommon_HEADER_FILES
     chrono.h
     classic_callback.h
     commoncontrol.h
+    coro_scheduler.h
     ctype_workaround.h
     fix_macros.h
     fsyspath.h
@@ -263,6 +266,7 @@ set(llcommon_HEADER_FILES
     threadpool.h
     threadpool_fwd.h
     threadsafeschedule.h
+    throttle.h
     timer.h
     tuple.h
     u64.h
diff --git a/indra/llcommon/coro_scheduler.cpp b/indra/llcommon/coro_scheduler.cpp
new file mode 100644
index 0000000000..337162cbd5
--- /dev/null
+++ b/indra/llcommon/coro_scheduler.cpp
@@ -0,0 +1,164 @@
+/**
+ * @file   coro_scheduler.cpp
+ * @author Nat Goodspeed
+ * @date   2024-08-05
+ * @brief  Implementation for llcoro::scheduler.
+ * 
+ * $LicenseInfo:firstyear=2024&license=viewerlgpl$
+ * Copyright (c) 2024, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+// Precompiled header
+#include "linden_common.h"
+// associated header
+#include "coro_scheduler.h"
+// STL headers
+// std headers
+#include <iomanip>
+// external library headers
+#include <boost/fiber/operations.hpp>
+// other Linden headers
+#include "llcallbacklist.h"
+#include "lldate.h"
+#include "llerror.h"
+
+namespace llcoro
+{
+
+const F32 scheduler::DEFAULT_TIMESLICE{ LL::Timers::DEFAULT_TIMESLICE };
+
+const std::string qname("General");
+
+scheduler::scheduler():
+    // Since use_scheduling_algorithm() must be called before any other
+    // Boost.Fibers operations, we can assume that the calling fiber is in
+    // fact the main fiber.
+    mMainID(boost::this_fiber::get_id()),
+    mStart(LLDate::now().secondsSinceEpoch()),
+    mQueue(LL::WorkQueue::getInstance(qname))
+{}
+
+void scheduler::awakened( boost::fibers::context* ctx) noexcept
+{
+    if (ctx->get_id() == mMainID)
+    {
+        // If the fiber that just came ready is the main fiber, record its
+        // pointer.
+        llassert(! mMainCtx);
+        mMainCtx = ctx;
+    }
+    // Delegate to round_robin::awakened() as usual, even for the main fiber.
+    // This way, as long as other fibers don't take too long, we can just let
+    // normal round_robin processing pass control to the main fiber.
+    super::awakened(ctx);
+}
+
+boost::fibers::context* scheduler::pick_next() noexcept
+{
+    // count calls to pick_next()
+    ++mSwitches;
+    // pick_next() is called when the previous fiber has suspended, and we
+    // need to pick another. Did the previous pick_next() call pick the main
+    // fiber? If so, it's the main fiber that just suspended.
+    auto now = LLDate::now().secondsSinceEpoch();
+    if (mMainRunning)
+    {
+        mMainRunning = false;
+        mMainLast = now;
+    }
+
+    boost::fibers::context* next;
+
+    // When the main fiber is ready, and it's been more than mTimeslice since
+    // the main fiber last ran, it's time to intervene.
+    F32 elapsed(now - mMainLast);
+    if (mMainCtx && elapsed > mTimeslice)
+    {
+        // We claim that the main fiber is not only stored in mMainCtx, but is
+        // also queued (somewhere) in our ready list.
+        llassert(mMainCtx->ready_is_linked());
+        // The usefulness of a doubly-linked list is that, given only a
+        // pointer to an item, we can unlink it.
+        mMainCtx->ready_unlink();
+        // Instead of delegating to round_robin::pick_next() to pop the head
+        // of the queue, override by returning mMainCtx.
+        next = mMainCtx;
+
+        /*------------------------- logging stuff --------------------------*/
+        // Unless this log tag is enabled, don't even bother posting.
+        LL_DEBUGS("LLCoros.scheduler");
+        // This feature is inherently hard to verify. The logging in the
+        // lambda below seems useful, but also seems like a lot of overhead
+        // for a coroutine context switch. Try posting the logging lambda to a
+        // ThreadPool to offload that overhead. However, if this is still
+        // taking an unreasonable amount of context-switch time, this whole
+        // passage could be skipped.
+
+        // Record this event for logging, but push it off to a thread pool to
+        // perform that work. Presumably std::weak_ptr::lock() is cheaper than
+        // WorkQueue::getInstance().
+        LL::WorkQueue::ptr_t queue{ mQueue.lock() };
+        // We probably started before the relevant WorkQueue was created.
+        if (! queue)
+        {
+            // Try again to locate the specified WorkQueue.
+            queue = LL::WorkQueue::getInstance(qname);
+            mQueue = queue;
+        }
+        // Both the lock() call and the getInstance() call might have failed.
+        if (queue)
+        {
+            // Bind values. Do NOT bind 'this' to avoid cross-thread access!
+            // It would be interesting to know from what queue position we
+            // unlinked the main fiber, out of how many in the ready list.
+            // Unfortunately round_robin::rqueue_ is private, not protected,
+            // so we have no access.
+            queue->post(
+                [switches=mSwitches, start=mStart, elapsed, now]
+                ()
+                {
+                    U32 runtime(U32(now) - U32(start));
+                    U32 minutes(runtime / 60u);
+                    U32 seconds(runtime % 60u);
+                    // use stringize to avoid lasting side effects to the
+                    // logging ostream
+                    LL_DEBUGS("LLCoros.scheduler")
+                        << "At time "
+                        << stringize(minutes, ":", std::setw(2), std::setfill('0'), seconds)
+                        << " (" << switches << " switches), coroutines took "
+                        << stringize(std::setprecision(4), elapsed)
+                        << " sec, main coroutine jumped queue"
+                        << LL_ENDL;
+                });
+        }
+        LL_ENDL;
+        /*----------------------- end logging stuff ------------------------*/
+    }
+    else
+    {
+        // Either the main fiber isn't yet ready, or it hasn't yet been
+        // mTimeslice seconds since the last time the main fiber ran. Business
+        // as usual.
+        next = super::pick_next();
+    }
+
+    // super::pick_next() could also have returned the main fiber, which is
+    // why this is a separate test instead of being folded into the override
+    // case above.
+    if (next && next->get_id() == mMainID)
+    {
+        // we're about to resume the main fiber: it's no longer "ready"
+        mMainCtx = nullptr;
+        // instead, it's "running"
+        mMainRunning = true;
+    }
+    return next;
+}
+
+void scheduler::use()
+{
+    boost::fibers::use_scheduling_algorithm<scheduler>();
+}
+
+} // namespace llcoro
diff --git a/indra/llcommon/coro_scheduler.h b/indra/llcommon/coro_scheduler.h
new file mode 100644
index 0000000000..a7572ccf4d
--- /dev/null
+++ b/indra/llcommon/coro_scheduler.h
@@ -0,0 +1,73 @@
+/**
+ * @file   coro_scheduler.h
+ * @author Nat Goodspeed
+ * @date   2024-08-05
+ * @brief  Custom scheduler for viewer's Boost.Fibers (aka coroutines)
+ * 
+ * $LicenseInfo:firstyear=2024&license=viewerlgpl$
+ * Copyright (c) 2024, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+#if ! defined(LL_CORO_SCHEDULER_H)
+#define LL_CORO_SCHEDULER_H
+
+#include "workqueue.h"
+#include <boost/fiber/fiber.hpp>
+#include <boost/fiber/algo/round_robin.hpp>
+
+/**
+ * llcoro::scheduler is specifically intended for the viewer's main thread.
+ * Its role is to ensure that the main coroutine, responsible for UI
+ * operations and coordinating everything else, doesn't get starved by
+ * secondary coroutines -- however many of those there might be.
+ *
+ * The simple boost::fibers::algo::round_robin scheduler could result in
+ * arbitrary time lag between resumptions of the main coroutine. Of course
+ * every well-behaved viewer coroutine must be coded to yield before too much
+ * real time has elapsed, but sheer volume of secondary coroutines could still
+ * consume unreasonable real time before cycling back to the main coroutine.
+ */
+
+namespace llcoro
+{
+
+class scheduler: public boost::fibers::algo::round_robin
+{
+    using super = boost::fibers::algo::round_robin;
+public:
+    // If the main fiber is ready, and it's been at least this long since the
+    // main fiber last ran, jump the main fiber to the head of the queue.
+    static const F32 DEFAULT_TIMESLICE;
+
+    scheduler();
+    void awakened( boost::fibers::context*) noexcept override;
+    boost::fibers::context* pick_next() noexcept override;
+
+    static void use();
+
+private:
+    // This is the fiber::id of the main fiber. We use this to discover
+    // whether the fiber passed to awakened() is in fact the main fiber.
+    boost::fibers::fiber::id mMainID;
+    // This context* is nullptr until awakened() notices that the main fiber
+    // has become ready, at which point it contains the main fiber's context*.
+    boost::fibers::context* mMainCtx{};
+    // Set when pick_next() returns the main fiber.
+    bool mMainRunning{ false };
+    // If it's been at least this long since the last time the main fiber got
+    // control, jump it to the head of the queue.
+    F32 mTimeslice{ DEFAULT_TIMESLICE };
+    // Timestamp as of the last time we suspended the main fiber.
+    F32 mMainLast{ 0 };
+    // Timestamp of start time
+    F32 mStart{ 0 };
+    // count context switches
+    U64 mSwitches{ 0 };
+    // WorkQueue for deferred logging
+    LL::WorkQueue::weak_t mQueue;
+};
+
+} // namespace llcoro
+
+#endif /* ! defined(LL_CORO_SCHEDULER_H) */
diff --git a/indra/llcommon/llcallbacklist.cpp b/indra/llcommon/llcallbacklist.cpp
index 555c793333..647b268b8b 100644
--- a/indra/llcommon/llcallbacklist.cpp
+++ b/indra/llcommon/llcallbacklist.cpp
@@ -391,7 +391,7 @@ public:
     TimersListener(const LazyEventAPIParams& params): LLEventAPI(params) {}
 
     // Forbid a script from requesting callbacks too quickly.
-    static constexpr LLSD::Real MINTIMER{ 1.0 };
+    static constexpr LLSD::Real MINTIMER{ 0.010 };
 
     void scheduleAfter(const LLSD& params);
     void scheduleEvery(const LLSD& params);
diff --git a/indra/llcommon/throttle.cpp b/indra/llcommon/throttle.cpp
new file mode 100644
index 0000000000..d5f7d5dcab
--- /dev/null
+++ b/indra/llcommon/throttle.cpp
@@ -0,0 +1,34 @@
+/**
+ * @file   throttle.cpp
+ * @author Nat Goodspeed
+ * @date   2024-08-12
+ * @brief  Implementation for ThrottleBase.
+ * 
+ * $LicenseInfo:firstyear=2024&license=viewerlgpl$
+ * Copyright (c) 2024, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+// Precompiled header
+#include "linden_common.h"
+// associated header
+#include "throttle.h"
+// STL headers
+// std headers
+// external library headers
+// other Linden headers
+#include "lltimer.h"
+
+bool ThrottleBase::too_fast()
+{
+    F64 now = LLTimer::getElapsedSeconds();
+    if (now < mNext)
+    {
+        return true;
+    }
+    else
+    {
+        mNext = now + mInterval;
+        return false;
+    }
+}
diff --git a/indra/llcommon/throttle.h b/indra/llcommon/throttle.h
new file mode 100644
index 0000000000..481d1d8f72
--- /dev/null
+++ b/indra/llcommon/throttle.h
@@ -0,0 +1,138 @@
+/**
+ * @file   throttle.h
+ * @author Nat Goodspeed
+ * @date   2024-08-12
+ * @brief  Throttle class
+ * 
+ * $LicenseInfo:firstyear=2024&license=viewerlgpl$
+ * Copyright (c) 2024, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+#if ! defined(LL_THROTTLE_H)
+#define LL_THROTTLE_H
+
+#include "apply.h"                  // LL::bind_front()
+#include "llerror.h"
+#include <functional>
+#include <iomanip>                  // std::quoted()
+
+class ThrottleBase
+{
+public:
+    ThrottleBase(F64 interval):
+        mInterval(interval)
+    {}
+
+protected:
+    bool too_fast();                // not const: we update mNext
+    F64 mInterval, mNext{ 0. };
+};
+
+/**
+ * An instance of Throttle mediates calls to some other specified function,
+ * ensuring that it's called no more often than the specified time interval.
+ * Throttle is an abstract base class that delegates the behavior when the
+ * specified interval is exceeded.
+ */
+template <typename SIGNATURE>
+class Throttle: public ThrottleBase
+{
+public:
+    Throttle(const std::string& desc,
+             const std::function<SIGNATURE>& func,
+             F64 interval):
+        ThrottleBase(interval),
+        mDesc(desc),
+        mFunc(func)
+    {}
+    // Constructing Throttle with a member function pointer but without an
+    // instance pointer requires you to pass the instance pointer/reference as
+    // the first argument to operator()().
+    template <typename R, class C>
+    Throttle(const std::string& desc, R C::* method, F64 interval):
+        Throttle(desc, std::mem_fn(method), interval)
+    {}
+    template <typename R, class C>
+    Throttle(const std::string& desc, R C::* method, C* instance, F64 interval):
+        Throttle(desc, LL::bind_front(method, instance), interval)
+    {}
+    template <typename R, class C>
+    Throttle(const std::string& desc, R C::* method, const C* instance, F64 interval):
+        Throttle(desc, LL::bind_front(method, instance), interval)
+    {}
+    virtual ~Throttle() {}
+
+    template <typename... ARGS>
+    auto operator()(ARGS... args)
+    {
+        if (too_fast())
+        {
+            suppress();
+            using rtype = decltype(mFunc(std::forward<ARGS>(args)...));
+            if constexpr (! std::is_same_v<rtype, void>)
+            {
+                return rtype{};
+            }
+        }
+        else
+        {
+            return mFunc(std::forward<ARGS>(args)...);
+        }
+    }
+
+protected:
+    // override with desired behavior when calls come too often
+    virtual void suppress() = 0;
+    const std::string mDesc;
+
+private:
+    std::function<SIGNATURE> mFunc;
+};
+
+/**
+ * An instance of LogThrottle mediates calls to some other specified function,
+ * ensuring that it's called no more often than the specified time interval.
+ * When that interval is exceeded, it logs a message at the specified log
+ * level. It uses LL_MUMBLES_ONCE() logic to prevent spamming, since a too-
+ * frequent call may well be spammy.
+ */
+template <LLError::ELevel LOGLEVEL, typename SIGNATURE>
+class LogThrottle: public Throttle<SIGNATURE>
+{
+    using super = Throttle<SIGNATURE>;
+public:
+    LogThrottle(const std::string& desc,
+                const std::function<SIGNATURE>& func,
+                F64 interval):
+        super(desc, func, interval)
+    {}
+    template <typename R, class C>
+    LogThrottle(const std::string& desc, R C::* method, F64 interval):
+        super(desc, method, interval)
+    {}
+    template <typename R, class C>
+    LogThrottle(const std::string& desc, R C::* method, C* instance, F64 interval):
+        super(desc, method, instance, interval)
+    {}
+    template <typename R, class C>
+    LogThrottle(const std::string& desc, R C::* method, const C* instance, F64 interval):
+        super(desc, method, instance, interval)
+    {}
+
+private:
+    void suppress() override
+    {
+        // Using lllog(), the macro underlying LL_WARNS() et al., allows
+        // specifying compile-time LOGLEVEL. It does NOT support a variable
+        // LOGLEVEL, which is why LOGLEVEL is a non-type template parameter.
+        // See llvlog() for variable support, which is a bit more expensive.
+        // true = only print the log message once
+        lllog(LOGLEVEL, true, "LogThrottle") << std::quoted(super::mDesc)
+                                             << " called more than once per "
+                                             << super::mInterval
+                                             << LL_ENDL;
+    }
+};
+
+#endif /* ! defined(LL_THROTTLE_H) */