EntropyEngine::Core::Concurrency::IWorkScheduler

EntropyEngine::Core::Concurrency::IWorkScheduler

Abstract interface for work scheduling strategies in the WorkService. More…

#include <IWorkScheduler.h>

Inherited by EntropyEngine::Core::Concurrency::AdaptiveRankingScheduler, EntropyEngine::Core::Concurrency::DirectScheduler, EntropyEngine::Core::Concurrency::RandomScheduler, EntropyEngine::Core::Concurrency::RoundRobinScheduler, EntropyEngine::Core::Concurrency::SpinningDirectScheduler

Public Classes

	Name
struct	ScheduleResult Result of a scheduling decision.
struct	Config Configuration for scheduler behavior.

Public Functions

	Name
virtual	~IWorkScheduler() =default
virtual ScheduleResult	selectNextGroup(const std::vector< WorkContractGroup * > & groups) =0 Selects the next work group for execution.
virtual void	reset() Resets scheduler to initial state.
virtual void	notifyWorkExecuted(WorkContractGroup * group, size_t threadId) Notifies scheduler that work was successfully executed.
virtual void	notifyGroupsChanged(const std::vector< WorkContractGroup * > & newGroups) Notifies scheduler that the group list has changed.
virtual const char *	getName() const =0 Gets human-readable name for this scheduling strategy.

Detailed Description

class EntropyEngine::Core::Concurrency::IWorkScheduler;

Abstract interface for work scheduling strategies in the WorkService.

IWorkScheduler defines the decision-making component that determines work execution order. The WorkService manages threading and execution infrastructure while the scheduler provides the selection logic. This separation enables experimentation with different scheduling strategies without modifying the core thread management system.

Implementation rationale: Custom schedulers enable optimizations for specific workload patterns such as round-robin fairness, priority-based scheduling, or adaptive strategies. While the default AdaptiveRankingScheduler handles most use cases effectively, specialized workloads may benefit from simpler implementations with lower overhead or more targeted scheduling algorithms.

Thread Safety: Implementations MUST be thread-safe. Multiple worker threads will invoke selectNextGroup() concurrently, potentially with identical group sets. Utilize atomics, thread-local storage, or lock-free algorithms to ensure correctness.

Design Requirements: selectNextGroup() executes within worker thread loops. Consider the frequency of calls when designing implementations.

// Example custom scheduler that always picks the group with most work
class GreedyScheduler : public IWorkScheduler {
public:
    ScheduleResult selectNextGroup(
        const std::vector<WorkContractGroup*>& groups,
        const SchedulingContext& context) override
    {
        WorkContractGroup* best = nullptr;
        size_t maxWork = 0;

        for (auto* group : groups) {
            size_t work = group->scheduledCount();
            if (work > maxWork) {
                maxWork = work;
                best = group;
            }
        }

        return {best, best == nullptr};
    }

    const char* getName() const override { return "Greedy"; }
};

Public Functions Documentation

function ~IWorkScheduler

virtual ~IWorkScheduler() =default

function selectNextGroup

virtual ScheduleResult selectNextGroup(
    const std::vector< WorkContractGroup * > & groups
) =0

Selects the next work group for execution.

Parameters:

• groups Current snapshot of registered work groups (groups might have no work)

Return: ScheduleResult with chosen group (or nullptr if no work found)

Reimplemented by: EntropyEngine::Core::Concurrency::AdaptiveRankingScheduler::selectNextGroup, EntropyEngine::Core::Concurrency::DirectScheduler::selectNextGroup, EntropyEngine::Core::Concurrency::RandomScheduler::selectNextGroup, EntropyEngine::Core::Concurrency::RoundRobinScheduler::selectNextGroup, EntropyEngine::Core::Concurrency::SpinningDirectScheduler::selectNextGroup

Core scheduling method called continuously by worker threads. Examines available groups and selects one for execution. Called frequently - avoid allocations and complexity.

// Simplest possible implementation - just find first group with work
ScheduleResult selectNextGroup(groups) override {
    for (auto* group : groups) {
        if (group->scheduledCount() > 0) {
            return {group, false};
        }
    }
    return {nullptr, true};  // No work, suggest sleep
}

function reset

inline virtual void reset()

Resets scheduler to initial state.

Reimplemented by: EntropyEngine::Core::Concurrency::AdaptiveRankingScheduler::reset, EntropyEngine::Core::Concurrency::RandomScheduler::reset, EntropyEngine::Core::Concurrency::RoundRobinScheduler::reset

Clear all accumulated state, statistics, and learned patterns. Scheduler should behave like newly constructed. Default is no-op.

function notifyWorkExecuted

inline virtual void notifyWorkExecuted(
    WorkContractGroup * group,
    size_t threadId
)

Notifies scheduler that work was successfully executed.

Parameters:

• group The group that work was executed from
• threadId The thread that executed the work

Reimplemented by: EntropyEngine::Core::Concurrency::AdaptiveRankingScheduler::notifyWorkExecuted, EntropyEngine::Core::Concurrency::RandomScheduler::notifyWorkExecuted, EntropyEngine::Core::Concurrency::RoundRobinScheduler::notifyWorkExecuted

Optional callback for tracking execution patterns. Use for adapting behavior, balancing load, or maintaining fairness. Default is no-op.

function notifyGroupsChanged

inline virtual void notifyGroupsChanged(
    const std::vector< WorkContractGroup * > & newGroups
)

Notifies scheduler that the group list has changed.

Parameters:

• newGroups Updated list of work groups (complete replacement)

Reimplemented by: EntropyEngine::Core::Concurrency::AdaptiveRankingScheduler::notifyGroupsChanged

Called when groups are added/removed. Update cached state if needed. Runs concurrently with selectNextGroup() - ensure thread safety.

function getName

virtual const char * getName() const =0

Gets human-readable name for this scheduling strategy.

Return: Name of the scheduling algorithm (must be a static string)

Reimplemented by: EntropyEngine::Core::Concurrency::AdaptiveRankingScheduler::getName, EntropyEngine::Core::Concurrency::DirectScheduler::getName, EntropyEngine::Core::Concurrency::RandomScheduler::getName, EntropyEngine::Core::Concurrency::RoundRobinScheduler::getName, EntropyEngine::Core::Concurrency::SpinningDirectScheduler::getName

Used in logs and debugging. Keep concise and descriptive.

---

Updated on 2026-01-26 at 16:50:32 -0500