API — ICoreEssentials/Concurrency

The public contract of 2 header(s) under ICoreEssentials/Concurrency — 4 class/struct definition(s), 38 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreThread.h#

ICoreEssentials/Concurrency/ICoreThread.h

ICoreThread#

ICoreThread.h:75 · class · 2 declaration(s)

ICoreThread -- the answer to "which thread am I on".

class ICoreThread {
public:
    ICoreThread() = delete;

    // "Is the calling thread the GUI thread?" -- used to decide whether work
    // can touch widgets or has to be posted over. Static because the caller
    // asking it holds no thread object at all; there is no longer one to hold.
    [[nodiscard]] static bool isMainThread() noexcept;
};
};

ICoreThreadPool.h#

ICoreEssentials/Concurrency/ICoreThreadPool.h

ICoreThreadPool -- run work off the main thread, and come back to it.

// Fire and forget: ICoreThreadPool::global().start([] { rebuildIndex(); });

// Work on a worker, then continue on the main thread: ICoreThreadPool::global().run( [path] { parse(path); }, // worker thread [](const ICoreFuture& f) { // main thread, once if (f.hasFailed()) showError(f.errorString()); });

// A result: ICoreThreadPool::global().runWithResult<int>(

ICoreCancellationToken#

ICoreThreadPool.h:51 · class · pImpl · 6 declaration(s)

A shared flag: copies observe the same cancel().

class ICoreCancellationToken {
public:
    ICoreCancellationToken();
    ~ICoreCancellationToken();
    ICoreCancellationToken(const ICoreCancellationToken& other);
    ICoreCancellationToken& operator=(const ICoreCancellationToken& other);

    void cancel() noexcept;
    [[nodiscard]] bool isCancelled() const noexcept;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreFuture#

ICoreThreadPool.h:70 · class · pImpl · 13 declaration(s)

A handle on one submitted task.

class ICoreFuture {
public:
    ICoreFuture();
    ~ICoreFuture();
    ICoreFuture(const ICoreFuture& other);
    ICoreFuture& operator=(const ICoreFuture& other);

    // Waits until the task has finished, failed or been cancelled; a negative
    // timeout waits for as long as it takes. True when it is done.
    bool wait(int timeoutMs) const;
    bool wait() const;

    // Done in any way: ran to the end, threw, or was cancelled.
    [[nodiscard]] bool isFinished() const noexcept;
    [[nodiscard]] bool isRunning() const noexcept;
    [[nodiscard]] bool isCancelled() const noexcept;
    [[nodiscard]] bool hasFailed() const noexcept;
    [[nodiscard]] std::string errorString() const;

    // Stops it starting if it has not; signals its token either way.
    void cancel() noexcept;
    [[nodiscard]] ICoreCancellationToken token() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreThreadPool#

ICoreThreadPool.h:99 · class · pImpl · 17 declaration(s)

class ICoreThreadPool {
public:
    // As many threads as the machine has hardware threads.
    ICoreThreadPool();
    explicit ICoreThreadPool(int maxThreads);
    ~ICoreThreadPool();

    ICoreThreadPool(const ICoreThreadPool&) = delete;
    ICoreThreadPool& operator=(const ICoreThreadPool&) = delete;

    // The application-wide pool.
    static ICoreThreadPool& global();

    void start(std::function<void()> task);
    ICoreFuture submit(std::function<void()> task);
    // The token handed to the task is the returned future's.
    ICoreFuture submit(std::function<void(const ICoreCancellationToken&)> task);

    // `work` on a worker, then `done` on the main thread, exactly once, however
    // the work ended (inspect the future it is given).
    ICoreFuture run(std::function<void()> work, std::function<void(const ICoreFuture&)> done);

    // A typed convenience over run(): `done` gets the value when `work`
    // returned one; it is not called when the work threw or was cancelled.
    template <typename T>
    ICoreFuture runWithResult(std::function<T()> work, std::function<void(T)> done) {
        auto value = std::make_shared<T>();
        return run([work = std::move(work), value] { *value = work(); },
                   [done = std::move(done), value](const ICoreFuture& f) {
                       if (!f.hasFailed() && !f.isCancelled()) done(std::move(*value));
                   });
    }

    // Waits until nothing is queued or running; false on timeout.
    bool waitForDone(int timeoutMs);
    bool waitForDone();

    // Cancels every task not yet started.
    void clear();

    [[nodiscard]] int maxThreadCount() const noexcept;
    [[nodiscard]] int activeThreadCount() const;
    [[nodiscard]] int queuedTaskCount() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};