pw::work_queue::WorkQueue Class Reference

#include <work_queue.h>

Inheritance diagram for pw::work_queue::WorkQueue:

Public Member Functions
	WorkQueue (InlineQueue< WorkItem > &queue, size_t queue_capacity)
Status	PushWork (WorkItem &&work_item)
void	CheckPushWork (WorkItem &&work_item)
void	RequestStop ()

Detailed Description

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.

Constructor & Destructor Documentation

WorkQueue()

pw::work_queue::WorkQueue::WorkQueue ( InlineQueue< WorkItem > &  queue, size_t  queue_capacity  )

inline

Parameters

[in]	queue	The work entries to enqueue.
[in]	queue_capacity	The internal queue size which limits the number of outstanding work requests.

Note

The ThreadNotification prevents this from being constexpr.

Member Function Documentation

CheckPushWork()

void pw::work_queue::WorkQueue::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

[in]

work_item

The entry to enqueue.

Precondition

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

PushWork()

Status pw::work_queue::WorkQueue::PushWork ( WorkItem &&  work_item )

inline

Enqueues a work_item for execution by the work queue thread.

Parameters

[in]

work_item

The entry to enqueue.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     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.
* 
*  

RequestStop()

void pw::work_queue::WorkQueue::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.

---

The documentation for this class was generated from the following file:

• pw_work_queue/public/pw_work_queue/work_queue.h