pw_work_queue#

The pw_work_queue module contains utilities for deferring work to be executed by another thread.

Warning

This module is still under construction; the API is not yet stable.

Example#

#include "pw_thread/detached_thread.h"
#include "pw_work_queue/work_queue.h"

pw::work_queue::WorkQueueWithBuffer<10> work_queue;

pw::thread::Options& WorkQueueThreadOptions();
void SomeLongRunningProcessing();

void SomeInterruptHandler() {
    // Instead of executing the long running processing task in the interrupt,
    // the work_queue executes it on the interrupt's behalf.
    work_queue.CheckPushWork(SomeLongRunningProcessing);
}

int main() {
    // Start up the work_queue as a detached thread which runs forever.
    pw::thread::DetachedThread(WorkQueueThreadOptions(), work_queue);
}

API reference#

namespace work_queue#

Typedefs

using WorkItem = Function<void()>#
class WorkQueue : public thread::ThreadCore#

Enables threads and interrupts to enqueue work as a pw::work_queue::WorkItem for execution by the work queue.

Queue sizing: The number of outstanding work requests is limited based on the internal queue size. The queue size is set through either the size of the queue_storage buffer passed into the constructor or by using the templated pw::work_queue::WorkQueueWithBuffer helper. When the queue is full, the queue will not accept further work.

Cooperative thread cancellation: The class is a pw::thread::ThreadCore, meaning it should be executed as a single thread. To facilitate clean shutdown, it provides a RequestStop() method for cooperative cancellation which should be invoked before joining the thread. Once a stop has been requested the queue will no longer accept further work.

The entire API is thread-safe and interrupt-safe.

Subclassed by pw::work_queue::WorkQueueWithBuffer< kWorkQueueEntries >

Public Functions

inline WorkQueue(InlineQueue<WorkItem> &queue, size_t queue_capacity)#

Note

The ThreadNotification prevents this from being constexpr.

Parameters:

  • queue – [in] The work entries to enqueue.

  • queue_capacity – [in] The internal queue size which limits the number of outstanding work requests.

inline Status PushWork(WorkItem &&work_item)#

Enqueues a work_item for execution by the work queue thread.

Parameters:

work_item – [in] The entry to enqueue.

Returns:

Code

Description

OK

Success. Entry was enqueued for execution.

FAILED_PRECONDITION

The work queue is shutting down. Entries are no longer permitted.

RESOURCE_EXHAUSTED

Internal work queue is full. Entry was not enqueued.

void CheckPushWork(WorkItem &&work_item)#

Queues work for execution. Crashes if the work cannot be queued due to a full queue or a stopped worker thread.

This call is recommended where possible since it saves error handling code at the callsite; and in many practical cases, it is a bug if the work queue is full (and so a crash is useful to detect the problem).

Parameters:

work_item – [in] The entry to enqueue.

Pre:

  • The queue must not overflow, i.e. be full.

  • The queue must not have been requested to stop, i.e. it must not be in the process of shutting down.

void RequestStop()#

Locks the queue to prevent further work enqueing, finishes outstanding work, then shuts down the worker thread.

The WorkQueue cannot be resumed after stopping because the ThreadCore thread returns and may be joined. The WorkQueue must be reconstructed for re-use after the thread has been joined.

template<size_t kWorkQueueEntries>
class WorkQueueWithBuffer : public pw::work_queue::WorkQueue#