pw_work_queue#

Stable

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

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);
}

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

struct MyWorkItem {
  int value;
};

pw::work_queue::CustomWorkQueueWithBuffer<10, MyWorkItem> work_queue(
   [](MyWorkItem& item) {
     SomeLongRunningProcessing(item);
   });
pw::thread::Options& WorkQueueThreadOptions();
void SomeLongRunningProcessing(MyWorkItem& value);

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

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#
template<typename WorkItem>
class CustomWorkQueue : 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::CustomWorkQueueWithBuffer< kWorkQueueEntries, WorkItem >

Public Functions

inline CustomWorkQueue(InlineQueue<WorkItem> &queue, pw::Function<void(WorkItem&)> &&fn)#

Note

The ThreadNotification prevents this from being constexpr.

Parameters:

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

  • fn – [in] The function to invoke on each enqueued WorkItem

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.

inline 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.

inline 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, typename WorkItem>
class CustomWorkQueueWithBuffer : public pw::work_queue::CustomWorkQueue<WorkItem>#

Creates a WorkQueue and the backing queue.

Param kWorkQueueEntries:

The number of entries in the work queue

Param WorkItem:

The type that will enqueued.

Public Functions

inline constexpr CustomWorkQueueWithBuffer(pw::Function<void(WorkItem&)> &&fn)#
Parameters:

fn – [in] The function to invoke on each enqueued WorkItem

class WorkQueue : public pw::work_queue::CustomWorkQueue<Closure>#

Creates a WorkQueue.

WorkQueue enqueues pw_function::Closure and the worker thread invokes the Closure.

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

Public Functions

inline WorkQueue(InlineQueue<Closure> &queue)#
Parameters:

queue – [in] The work entries to enqueue.

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

Creates a WorkQueue and the backing queue.

WorkQueueWithBuffer enqueues pw_function::Closure and the worker thread invokes the Closure.

Param kWorkQueueEntries:

The number of entries in the work queue (e.g. the total number of work requests before the queue is full).

On this page