folly::SerialExecutor Class Reference

Executor that guarantees serial non-concurrent execution of added tasks. More...

#include <SerialExecutor.h>

Inheritance diagram for folly::SerialExecutor:

Classes
class	Deleter

Public Types
using	UniquePtr = std::unique_ptr< SerialExecutor, Deleter >

Public Member Functions
	SerialExecutor (SerialExecutor const &)=delete
SerialExecutor &	operator= (SerialExecutor const &)=delete
	SerialExecutor (SerialExecutor &&)=delete
SerialExecutor &	operator= (SerialExecutor &&)=delete
void	add (Func func) override
void	addWithPriority (Func func, int8_t priority) override
uint8_t	getNumPriorities () const override
Public Member Functions inherited from folly::Executor
virtual	~Executor ()

Static Public Member Functions
static KeepAlive< SerialExecutor >	create (KeepAlive< Executor > parent=getKeepAliveToken(getCPUExecutor().get()))
static UniquePtr	createUnique (std::shared_ptr< Executor > parent=getCPUExecutor())
Static Public Member Functions inherited from folly::Executor
template<typename ExecutorT >
static KeepAlive< ExecutorT >	getKeepAliveToken (ExecutorT *executor)
template<typename ExecutorT >
static KeepAlive< ExecutorT >	getKeepAliveToken (ExecutorT &executor)

Protected Member Functions
bool	keepAliveAcquire () override
void	keepAliveRelease () override

Private Member Functions
	SerialExecutor (KeepAlive< Executor > parent)
	~SerialExecutor () override
void	run ()

Private Attributes
KeepAlive< Executor >	parent_
std::atomic< std::size_t >	scheduled_ {0}
folly::UnboundedQueue< Func, false, true, false >	queue_
std::atomic< ssize_t >	keepAliveCounter_ {1}

Additional Inherited Members
Static Public Attributes inherited from folly::Executor
static const int8_t	LO_PRI = SCHAR_MIN
static const int8_t	MID_PRI = 0
static const int8_t	HI_PRI = SCHAR_MAX
Static Protected Member Functions inherited from folly::Executor
template<typename ExecutorT >
static bool	isKeepAliveDummy (const KeepAlive< ExecutorT > &keepAlive)
template<typename ExecutorT >
static KeepAlive< ExecutorT >	makeKeepAlive (ExecutorT *executor)

Detailed Description

Executor that guarantees serial non-concurrent execution of added tasks.

SerialExecutor is similar to boost asio's strand concept. A SerialExecutor has a parent executor which is given at construction time (defaults to folly's global CPUExecutor). Tasks added to SerialExecutor are executed in the parent executor, however strictly non-concurrently and in the order they were added.

SerialExecutor tries to schedule its tasks fairly. Every task submitted to it results in one task submitted to the parent executor. Whenever the parent executor executes one of those, one of the tasks submitted to SerialExecutor is marked for execution, which means it will either be executed at once, or if a task is currently being executed already, after that.

The SerialExecutor may be deleted at any time. All tasks that have been submitted will still be executed with the same guarantees, as long as the parent executor is executing tasks.

Definition at line 52 of file SerialExecutor.h.

Member Typedef Documentation

using folly::SerialExecutor::UniquePtr = std::unique_ptr<SerialExecutor, Deleter>

Definition at line 78 of file SerialExecutor.h.

Constructor & Destructor Documentation

folly::SerialExecutor::SerialExecutor ( SerialExecutor const &  )

delete

folly::SerialExecutor::SerialExecutor ( SerialExecutor &&  )

delete

folly::SerialExecutor::SerialExecutor ( KeepAlive< Executor >  parent )

explicitprivate

folly::SerialExecutor::~SerialExecutor ( )

overrideprivate

Definition at line 28 of file SerialExecutor.cpp.

Referenced by getNumPriorities().

                                {
  DCHECK(!keepAliveCounter_);
}

Member Function Documentation

void folly::SerialExecutor::add ( Func  func )

overridevirtual

Add one task for execution in the parent executor

Implements folly::Executor.

Definition at line 59 of file SerialExecutor.cpp.

References folly::Executor::getKeepAliveToken(), and folly::gen::move.

                                  {
  queue_.enqueue(std::move(func));
  parent_->add([keepAlive = getKeepAliveToken(this)] { keepAlive->run(); });
}

void folly::SerialExecutor::addWithPriority ( Func  func, int8_t  priority  )

overridevirtual

Add one task for execution in the parent executor, and use the given priority for one task submission to parent executor.

Since in-order execution of tasks submitted to SerialExecutor is guaranteed, the priority given here does not necessarily reflect the execution priority of the task submitted with this call to addWithPriority. The given priority is passed on to the parent executor for the execution of one of the SerialExecutor's tasks.

Reimplemented from folly::Executor.

Definition at line 64 of file SerialExecutor.cpp.

References folly::Executor::getKeepAliveToken(), and folly::gen::move.

                                                               {
  queue_.enqueue(std::move(func));
  parent_->addWithPriority(
      [keepAlive = getKeepAliveToken(this)] { keepAlive->run(); }, priority);
}

Executor::KeepAlive< SerialExecutor > folly::SerialExecutor::create ( KeepAlive< Executor >  parent = getKeepAliveToken(getCPUExecutor().get()) )

static

Definition at line 32 of file SerialExecutor.cpp.

References folly::gen::move.

Referenced by folly::isSequencedExecutor(), and folly::TEST().

                                {
  return makeKeepAlive<SerialExecutor>(new SerialExecutor(std::move(parent)));
}

SerialExecutor::UniquePtr folly::SerialExecutor::createUnique ( std::shared_ptr< Executor >  parent = getCPUExecutor() )

static

Definition at line 37 of file SerialExecutor.cpp.

References folly::pushmi::executor, folly::Executor::getKeepAliveToken(), and folly::gen::move.

                                    {
  auto executor = new SerialExecutor(getKeepAliveToken(parent.get()));
  return {executor, Deleter{std::move(parent)}};
}

uint8_t folly::SerialExecutor::getNumPriorities ( ) const

inlineoverridevirtual

Reimplemented from folly::Executor.

Definition at line 98 of file SerialExecutor.h.

References keepAliveAcquire(), keepAliveRelease(), parent, folly::SerialExecutor::Deleter::parent_, run(), folly::SerialExecutor::Deleter::SerialExecutor, and ~SerialExecutor().

                                            {
    return parent_->getNumPriorities();
  }

bool folly::SerialExecutor::keepAliveAcquire ( )

overrideprotectedvirtual

Reimplemented from folly::Executor.

Definition at line 43 of file SerialExecutor.cpp.

Referenced by getNumPriorities().

                                      {
  auto keepAliveCounter =
      keepAliveCounter_.fetch_add(1, std::memory_order_relaxed);
  DCHECK(keepAliveCounter > 0);
  return true;
}

void folly::SerialExecutor::keepAliveRelease ( )

overrideprotectedvirtual

Reimplemented from folly::Executor.

Definition at line 50 of file SerialExecutor.cpp.

Referenced by getNumPriorities(), and folly::SerialExecutor::Deleter::operator()().

                                      {
  auto keepAliveCounter =
      keepAliveCounter_.fetch_sub(1, std::memory_order_acq_rel);
  DCHECK(keepAliveCounter > 0);
  if (keepAliveCounter == 1) {
    delete this;
  }
}

SerialExecutor& folly::SerialExecutor::operator= ( SerialExecutor const &  )

delete

SerialExecutor& folly::SerialExecutor::operator= ( SerialExecutor &&  )

delete

void folly::SerialExecutor::run ( )

private

Definition at line 70 of file SerialExecutor.cpp.

References folly::exceptionStr().

Referenced by getNumPriorities().

                         {
  // We want scheduled_ to guard side-effects of completed tasks, so we can't
  // use std::memory_order_relaxed here.
  if (scheduled_.fetch_add(1, std::memory_order_acquire) > 0) {
    return;
  }

  do {
    Func func;
    queue_.dequeue(func);

    try {
      func();
    } catch (std::exception const& ex) {
      LOG(ERROR) << "SerialExecutor: func threw unhandled exception "
                 << folly::exceptionStr(ex);
    } catch (...) {
      LOG(ERROR) << "SerialExecutor: func threw unhandled non-exception "
                    "object";
    }

    // We want scheduled_ to guard side-effects of completed tasks, so we can't
    // use std::memory_order_relaxed here.
  } while (scheduled_.fetch_sub(1, std::memory_order_release) > 1);
}

Member Data Documentation

std::atomic<ssize_t> folly::SerialExecutor::keepAliveCounter_ {1}

private

Definition at line 121 of file SerialExecutor.h.

KeepAlive<Executor> folly::SerialExecutor::parent_

private

Definition at line 113 of file SerialExecutor.h.

folly::UnboundedQueue<Func, false, true, false> folly::SerialExecutor::queue_

private

Unbounded multi producer single consumer queue where consumers don't block on dequeue.

Definition at line 119 of file SerialExecutor.h.

std::atomic<std::size_t> folly::SerialExecutor::scheduled_ {0}

private

Definition at line 114 of file SerialExecutor.h.

---

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

• proxygen/folly/folly/executors/SerialExecutor.h
• proxygen/folly/folly/executors/SerialExecutor.cpp