Executor.hpp

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include "../Api.hpp"
 
#include <coroutine>
#include <functional>
 
namespace Lightweight::Async
{
 
/// A unit of deferred work scheduled on an @ref IExecutor.
///
/// @c std::function (rather than @c std::move_only_function) is used so the async layer builds
/// with standard libraries that do not yet provide the latter; every work item the library posts
/// is a small, copyable closure.
using Work = std::function<void()>;
 
/// @ingroup Async
/// Interface for an executor that runs posted work items.
///
/// Executors are injected (dependency injection) and owned by the caller; the async layer
/// only ever holds references to them. Every implementation's @ref Post is thread-safe.
///
/// Marked @c LIGHTWEIGHT_API although it is header-only: the library's own executors
/// (@ref ThreadPoolExecutor, @ref StrandExecutor, @ref ManualExecutor) are exported and derive
/// from it, and MSVC requires the base of a dll-interface class to be dll-interface too —
/// otherwise every consumer that includes them gets warning C4275.
class LIGHTWEIGHT_API IExecutor
{
  public:
    IExecutor() = default;
    IExecutor(IExecutor const&) = delete;
    IExecutor& operator=(IExecutor const&) = delete;
    IExecutor(IExecutor&&) = delete;
    IExecutor& operator=(IExecutor&&) = delete;
    virtual ~IExecutor() = default;
 
    /// Schedules @p work to run on the executor. Thread-safe.
    ///
    /// @param work The work item to enqueue (consumed).
    virtual void Post(Work work) = 0;
};
 
/// @ingroup Async
/// Interface for scheduling the resumption of a suspended coroutine.
///
/// Kept separate from @ref IExecutor::Post so resumption can be expressed as a bare
/// coroutine handle, which lets implementations avoid wrapping every resume in a
/// @c Work allocation on hot paths.
///
/// Exported for the same reason as @ref IExecutor (C4275 on the exported executors).
class LIGHTWEIGHT_API IResumeScheduler
{
  public:
    IResumeScheduler() = default;
    IResumeScheduler(IResumeScheduler const&) = delete;
    IResumeScheduler& operator=(IResumeScheduler const&) = delete;
    IResumeScheduler(IResumeScheduler&&) = delete;
    IResumeScheduler& operator=(IResumeScheduler&&) = delete;
    virtual ~IResumeScheduler() = default;
 
    /// Schedules @p handle to be resumed. Thread-safe.
    ///
    /// @param handle The coroutine to resume.
    virtual void Resume(std::coroutine_handle<> handle) = 0;
};
 
/// @ingroup Async
/// An executor that runs work synchronously on the calling thread.
///
/// Useful for tests and for degenerate single-threaded configurations where no thread
/// hand-off is desired. Note that with synchronous ODBC drivers an @ref InlineExecutor
/// used as the offload target will block the calling thread for the duration of the call.
class InlineExecutor final: public IExecutor, public IResumeScheduler
{
  public:
    void Post(Work work) override
    {
        if (work)
            work();
    }
 
    void Resume(std::coroutine_handle<> handle) override
    {
        if (handle)
            handle.resume();
    }
};
 
} // namespace Lightweight::Async