load_balancer

#include <gempba/core/load_balancer.hpp>  // included automatically via gempba.hpp

Abstract interface for thread-level work distribution within a single process. node_manager holds a pointer to one and routes all submission calls through it.

Built-in implementations: Quasi-Horizontal (recommended), Work-Stealing (baseline).

---

Member types

enum balancing_policy { /* implementation-defined values */ };

Enum identifying the concrete strategy. Returned by get_balancing_policy().

---

Member functions

Configuration

virtual void set_thread_pool_size(unsigned int size) = 0;

Set number of worker threads. Call before submitting any work.

---

Task submission

virtual bool try_local_submit(node& p_node) = 0;

Attempt to push p_node to an idle thread. Returns false if pool is full — the caller must run the node inline.

virtual void forward(node& p_node) = 0;

Execute p_node on the calling thread immediately.

virtual bool try_remote_submit(node& p_node, int runnable_id) = 0;

Send p_node to another process via the wired-in scheduler. runnable_id selects the matching serial_runnable on the remote side. Only meaningful in multiprocessing mode.

virtual std::future<std::any> force_local_submit(std::function<std::any()>&&) = 0;

Submit an arbitrary callable to the thread pool and return a future. Internal use only.

---

Monitoring

[[nodiscard]] virtual double       get_idle_time()            const = 0;
[[nodiscard]] virtual bool         is_done()                  const = 0;
[[nodiscard]] virtual std::size_t  get_thread_request_count() const = 0;
[[nodiscard]] virtual unsigned int get_thread_pool_size()     const = 0;
[[nodiscard]] virtual std::size_t  get_tasks_running_count()  const = 0;

get_idle_time(): cumulative wall-clock seconds the pool spent waiting for work, averaged per thread.
is_done(): true when queue is empty and all threads are idle.
get_thread_request_count(): total tasks submitted since startup.
get_thread_pool_size(): current worker-thread count in the pool.
get_tasks_running_count(): tasks executing on the pool right now. Together with get_thread_pool_size() this is what telemetry samples for the live worker frames.

---

Synchronization

virtual void wait() = 0;

Block until all queued and in-flight tasks complete.

---

Per-thread root management

virtual std::shared_ptr<std::shared_ptr<node_core>>
    get_root(std::thread::id thread_id) = 0;

virtual void set_root(std::thread::id thread_id,
                      std::shared_ptr<node_core>& root) = 0;

Hooks for tracking a per-thread root pointer (quasi-horizontal strategy). Provide no-op stubs if unused.

---

Identification

virtual balancing_policy get_balancing_policy() = 0;

Enum value identifying this strategy.

virtual unsigned int generate_unique_id() = 0;

Monotonically increasing node ID. Called internally by node factory functions.

---

Custom implementation

class MyLoadBalancer : public gempba::load_balancer {
    // implement all pure virtuals above
};

auto* lb = gempba::create_load_balancer(std::make_unique<MyLoadBalancer>());

The BYO overload is mode-agnostic and lives at the top level of the gempba namespace; it behaves identically in MT and MP builds.

Study quasi_horizontal_load_balancer in private/impl/load_balancing/ for the expected semantics of every tree navigation call before writing from scratch.