WorkflowScheduler.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using static GenerallyPositive.Enums;
 
namespace GenerallyPositive.Browser
{
    public class WorkflowRun
    {
        public int Index { get; internal set; }
        public bool Succeeded { get; internal set; }
        public TimeSpan Duration { get; internal set; }
        public Exception Failure { get; internal set; }
    }

    public class WorkflowScheduler : IAllowScheduledWorkflow, IAllowScheduledWorkflowExecution
    {
        private readonly List<Action> workflows = new List<Action>();
        private int maxAtOnce = 1;
        private int staggerMs = 250;
        private int timeoutMs = Timeout.Infinite;
 
        internal WorkflowScheduler()
        {
        }

        public IAllowScheduledWorkflowExecution WithMaxAtOnce(int howMany)
        {
            if (1 > howMany)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Cannot run [{howMany}] at once, so one at a time it is", this, GPALObjectType.Browser);
                howMany = 1;
            }
 
            maxAtOnce = howMany;
 
            return this;
        }

        public IAllowScheduledWorkflowExecution WithStaggerStart(int delayInMs)
        {
            if (0 > delayInMs)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Cannot stagger by [{delayInMs}] ms, so they start together", this, GPALObjectType.Browser);
                delayInMs = 0;
            }
 
            staggerMs = delayInMs;
 
            return this;
        }

        public IAllowScheduledWorkflowExecution WithTimeout(int timeoutInMs)
        {
            timeoutMs = 0 < timeoutInMs ? timeoutInMs : Timeout.Infinite;
 
            return this;
        }

        public IAllowScheduledWorkflowExecution WithWorkflow(Action workflow)
        {
            if (null == workflow)
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Workflow is null in WithWorkflow, so an empty one was added instead", this, GPALObjectType.Browser);
 
            workflows.Add(workflow ?? (() => { }));
 
            return this;
        }

        public IAllowScheduledWorkflowExecution Run()
        {
            return Run(out List<WorkflowRun> ignored);
        }

        public IAllowScheduledWorkflowExecution Run(out List<WorkflowRun> runs)
        {
            List<Action> running = workflows.ToList();
            workflows.Clear();
 
            WorkflowRun[] report = running.Select((w, index) => new WorkflowRun { Index = index }).ToArray();
 
            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Running [{running.Count}] workflow(s), [{maxAtOnce}] at a time, [{staggerMs}] ms apart.", this, GPALObjectType.Browser);
 
            // the moment the last workflow was let go, so the next one can be held back to staggerMs after it
            object startLine = new object();
            DateTime lastStart = DateTime.MinValue;
 
            // not in a using: a workflow we gave up on is still holding a slot and still going to Release it,
            // and releasing a disposed semaphore throws on a thread nobody is watching. disposed below, when
            // the last of them is known to be done with it
            SemaphoreSlim gate = new SemaphoreSlim(maxAtOnce, maxAtOnce);
 
            Task[] started = running.Select((workflow, index) => Task.Run(() =>
            {
                gate.Wait();
 
                // held here rather than in the loop that made the tasks, so a workflow that waited on the
                // gate is spaced from the one before it too, not just from the one it was created after
                if (0 < staggerMs)
                {
                    lock (startLine)
                    {
                        TimeSpan gap = TimeSpan.FromMilliseconds(staggerMs);
                        TimeSpan since = DateTime.Now - lastStart;
 
                        // the first one through has waited since DateTime.MinValue, so it never sleeps
                        if (since < gap)
                            Thread.Sleep(gap - since);
 
                        lastStart = DateTime.Now;
                    }
                }
 
                // each task writes only its own entry, so the report needs no gate of its own
                WorkflowRun mine = report[index];
                DateTime began = DateTime.Now;
 
                try
                {
                    workflow();
                    mine.Succeeded = true;
                }
                catch (Exception ex)
                {
                    mine.Failure = ex;
 
                    GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Workflow [{index + 1}] failed", this, GPALObjectType.Browser, ex);
                }
                finally
                {
                    mine.Duration = DateTime.Now - began;
                    gate.Release();
                }
            })).ToArray();
 
            bool allFinished = Task.WaitAll(started, timeoutMs);
 
            // copies, so the list handed back says what was true when Run gave up. the entries themselves stay
            // live for any workflow still running, which would otherwise rewrite its own verdict afterwards
            runs = report.Select(run => new WorkflowRun
            {
                Index = run.Index,
                Succeeded = run.Succeeded,
                Duration = run.Duration,
                Failure = run.Failure ?? (true == run.Succeeded ? null : new TimeoutException($"Workflow [{run.Index + 1}] was still running after [{timeoutMs}] ms")),
            }).ToList();
 
            if (true == allFinished)
            {
                gate.Dispose();
 
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"All [{running.Count}] workflow(s) finished, [{runs.Count(r => false == r.Succeeded)}] of them failed.", this, GPALObjectType.Browser);
            }
            else
                // the semaphore is left undisposed on purpose: the workflows still running are still going to
                // release it, and it goes when they do rather than throwing on a thread nobody is watching
                GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                    $"Gave up waiting after [{timeoutMs}] ms with [{runs.Count(r => false == r.Succeeded)}] of [{running.Count}] workflow(s) still running. They keep going and keep their browsers.",
                    this, GPALObjectType.Browser);
 
            return this;
        }
    }
}