pause_token

---

A pause_token is the only synchronisation class in ZAB that has no standard library equivalent. It is used for pauseing and unpausing coroutines in a thread safe manner. All pause_token functions except the deconstructor are thread safe. The pause_token is constructed in a paused state.

If paused, coroutines that co_await the pause_token will have their execution suspended. Otherwise, co_await no-ops.

If the pause_token changes from a paused state to an unpaused state, all coroutines that had their execution suspended will be resumed in the same thread they were suspended in.

The pause_token is re-usable and can be switched between paused and unpaused states. There is no maximum number of coroutines that can be suspended. Although, unpausing is linear in the number of suspended coroutines.

---

Example

async_function<>
your_class::worker(thread_t _thread, pause_token& _pt)
{
    /* Move into our thread */
    co_await yield(_thread);

    /* If it was already unpaused this will just no-op */
    co_await _pt;

    std::cout << "At work " << _thread << "\n";
}


async_function<>
your_class::pause_example(pause_token& _pt)
{
    const auto threads = engine_->number_of_workers();
    pause_token pt(engine_);

    for (std::uint16_t t = 0; t < threads; ++t) {
        worker(thread_t{t}, pt);
    }

    /* wait 5 second... */
    co_await yield(order::seconds(5));

    std::cout << "Putting to work\n";
    pt.unpause();
}

---

class zab::pause_token

A thread-safe syncronization primitive for suspending and resuming groups of coroutines.

Public Functions

inline pause_token(engine *_engine)

Construct a new pause token object that uses the given engine for resumption.

The pause token is constructed in an unpaused state.

Parameters

_engine – The engine to use.

inline bool paused() const noexcept

Determine if the pause token is in a paused state.

Returns

true If paused.

Returns

false If no paused.

inline void pause() noexcept

Set the state of the pause token to pause.

No-ops if the token is already paused.

inline void unpause() noexcept

Set the state of the pause token to unpaused.

No-ops if the pause token is already unpaused.

    This function will resume any coroutines currently paused on the pause token
    into the thread they where suspended on.

    The resumption is not performed inlined, but is yielded.

inline pauser operator co_await() noexcept

Suspend the coroutine until the the pause token is unpaused.

@co_return void Suspend until unpaused.

---