folly::fibers::Baton Class Reference

#include <Baton.h>

Classes
class	FiberWaiter
class	TimeoutHandler
class	Waiter

Public Member Functions
	Baton () noexcept
	~Baton () noexcept=default
bool	ready () const
void	setWaiter (Waiter &waiter)
void	wait ()
void	wait (TimeoutHandler &timeoutHandler)
template<typename F >
void	wait (F &&mainContextFunc)
bool	try_wait ()
template<typename Rep , typename Period >
bool	try_wait_for (const std::chrono::duration< Rep, Period > &timeout)
template<typename Rep , typename Period , typename F >
bool	try_wait_for (const std::chrono::duration< Rep, Period > &timeout, F &&mainContextFunc)
template<typename Clock , typename Duration >
bool	try_wait_until (const std::chrono::time_point< Clock, Duration > &deadline)
template<typename Clock , typename Duration , typename F >
bool	try_wait_until (const std::chrono::time_point< Clock, Duration > &deadline, F &&mainContextFunc)
template<typename Clock , typename Duration , typename F >
bool	try_wait_for (const std::chrono::time_point< Clock, Duration > &deadline, F &&mainContextFunc)
template<typename Rep , typename Period >
bool	timed_wait (const std::chrono::duration< Rep, Period > &timeout)
	Alias to try_wait_for. Deprecated. More...
template<typename Rep , typename Period , typename F >
bool	timed_wait (const std::chrono::duration< Rep, Period > &timeout, F &&mainContextFunc)
	Alias to try_wait_for. Deprecated. More...
template<typename Clock , typename Duration >
bool	timed_wait (const std::chrono::time_point< Clock, Duration > &deadline)
	Alias to try_wait_until. Deprecated. More...
template<typename Clock , typename Duration , typename F >
bool	timed_wait (const std::chrono::time_point< Clock, Duration > &deadline, F &&mainContextFunc)
	Alias to try_wait_until. Deprecated. More...
void	post ()
void	reset ()

Private Types
enum	{ PreBlockAttempts = 300 }

Private Member Functions
	Baton (intptr_t state)
void	postHelper (intptr_t new_value)
void	postThread ()
void	waitThread ()
template<typename F >
void	waitFiber (FiberManager &fm, F &&mainContextFunc)
bool	spinWaitForEarlyPost ()
bool	timedWaitThread (TimeoutController::Duration timeout)

Private Attributes
union {
std::atomic< intptr_t >   waiter_
struct {
folly::detail::Futex   futex {}
int32_t   _unused_packing
}   futex_
};

Static Private Attributes
static constexpr intptr_t	NO_WAITER = 0
static constexpr intptr_t	POSTED = -1
static constexpr intptr_t	TIMEOUT = -2
static constexpr intptr_t	THREAD_WAITING = -3

Detailed Description

Primitive which allows one to put current Fiber to sleep and wake it from another Fiber/thread.

Definition at line 40 of file Baton.h.

Member Enumeration Documentation

anonymous enum

private

Enumerator

PreBlockAttempts

Must be positive. If multiple threads are actively using a higher-level data structure that uses batons internally, it is likely that the post() and wait() calls happen almost at the same time. In this state, we lose big 50% of the time if the wait goes to sleep immediately. On circa-2013 devbox hardware it costs about 7 usec to FUTEX_WAIT and then be awoken (half the t/iter as the posix_sem_pingpong test in BatonTests). We can improve our chances of early post by spinning for a bit, although we have to balance this against the loss if we end up sleeping any way. Spins on this hw take about 7 nanos (all but 0.5 nanos is the pause instruction). We give ourself 300 spins, which is about 2 usec of waiting. As a partial consolation, since we are using the pause instruction we are giving a speed boost to the colocated hyperthread.

Definition at line 236 of file Baton.h.

       {
    PreBlockAttempts = 300,
  };

Constructor & Destructor Documentation

folly::fibers::Baton::Baton ( )

inlinenoexcept

Definition at line 37 of file Baton-inl.h.

References futex_, POSTED, THREAD_WAITING, TIMEOUT, and waiter_.

Referenced by folly::fibers::Baton::Waiter::~Waiter().

                             : Baton(NO_WAITER) {
  assert(Baton(NO_WAITER).futex_.futex == static_cast<uint32_t>(NO_WAITER));
  assert(Baton(POSTED).futex_.futex == static_cast<uint32_t>(POSTED));
  assert(Baton(TIMEOUT).futex_.futex == static_cast<uint32_t>(TIMEOUT));
  assert(
      Baton(THREAD_WAITING).futex_.futex ==
      static_cast<uint32_t>(THREAD_WAITING));

  assert(futex_.futex.is_lock_free());
  assert(waiter_.is_lock_free());
}

folly::fibers::Baton::~Baton ( )

defaultnoexcept

Referenced by folly::fibers::Baton::Waiter::~Waiter().

folly::fibers::Baton::Baton ( intptr_t  state )

inlineexplicitprivate

Definition at line 255 of file Baton.h.

References postHelper(), postThread(), spinWaitForEarlyPost(), timedWaitThread(), waitFiber(), and waitThread().

: waiter_(state) {}

Member Function Documentation

void folly::fibers::Baton::post

(

)

Wakes up Fiber which was waiting on this Baton (or if no Fiber is waiting, next wait() call will return immediately).

Definition at line 150 of file Baton.cpp.

References POSTED, and postHelper().

Referenced by folly::coro::detail::BlockingWaitPromiseBase::FinalAwaiter::await_suspend(), postHelper(), TEST(), and folly::fibers::TimedMutex::unlock().

                 {
  postHelper(POSTED);
}

void folly::fibers::Baton::postHelper ( intptr_t  new_value )

private

Definition at line 154 of file Baton.cpp.

References NO_WAITER, post(), POSTED, postThread(), THREAD_WAITING, TIMEOUT, and waiter_.

Referenced by Baton(), post(), and wait().

                                         {
  auto waiter = waiter_.load();

  do {
    if (waiter == THREAD_WAITING) {
      assert(new_value == POSTED);

      return postThread();
    }

    if (waiter == POSTED || waiter == TIMEOUT) {
      return;
    }
  } while (!waiter_.compare_exchange_weak(waiter, new_value));

  if (waiter != NO_WAITER) {
    reinterpret_cast<Waiter*>(waiter)->post();
  }
}

void folly::fibers::Baton::postThread ( )

private

Definition at line 178 of file Baton.cpp.

References futex, futex_, folly::detail::futexWake(), POSTED, THREAD_WAITING, and waiter_.

Referenced by Baton(), and postHelper().

                       {
  auto expected = THREAD_WAITING;

  auto* futex = &futex_.futex;
  if (!waiter_.compare_exchange_strong(expected, POSTED)) {
    return;
  }
  futexWake(futex, 1);
}

bool folly::fibers::Baton::ready ( ) const

inline

Definition at line 55 of file Baton.h.

References POSTED, setWaiter(), try_wait(), wait(), and waiter_.

Referenced by try_wait().

                     {
    auto state = waiter_.load();
    return state == POSTED;
  }

void folly::fibers::Baton::reset

(

)

Reset's the baton (equivalent to destroying the object and constructing another one in place). Caller is responsible for making sure no one is waiting on/posting the baton when reset() is called.

Definition at line 188 of file Baton.cpp.

References NO_WAITER, and waiter_.

Referenced by timed_wait().

                  {
  waiter_.store(NO_WAITER, std::memory_order_relaxed);
}

void folly::fibers::Baton::setWaiter

(

Waiter &

waiter

)

Registers a waiter for the baton. The waiter will be notified when the baton is posted.

Definition at line 30 of file Baton.cpp.

References LIKELY, NO_WAITER, folly::fibers::Baton::Waiter::post(), POSTED, TIMEOUT, and waiter_.

Referenced by ready(), and waitFiber().

                                    {
  auto curr_waiter = waiter_.load();
  do {
    if (LIKELY(curr_waiter == NO_WAITER)) {
      continue;
    } else if (curr_waiter == POSTED || curr_waiter == TIMEOUT) {
      waiter.post();
      break;
    } else {
      throw std::logic_error("Some waiter is already waiting on this Baton.");
    }
  } while (!waiter_.compare_exchange_weak(
      curr_waiter, reinterpret_cast<intptr_t>(&waiter)));
}

bool folly::fibers::Baton::spinWaitForEarlyPost ( )

private

Spin for "some time" (see discussion on PreBlockAttempts) waiting for a post.

Returns

true if we received a post the spin wait, false otherwise. If the function returns true then Baton state is guaranteed to be POSTED

Definition at line 94 of file Baton.cpp.

References folly::asm_volatile_pause(), i, PreBlockAttempts, and try_wait().

Referenced by Baton(), timedWaitThread(), and waitThread().

                                 {
  static_assert(
      PreBlockAttempts > 0,
      "isn't this assert clearer than an uninitialized variable warning?");
  for (int i = 0; i < PreBlockAttempts; ++i) {
    if (try_wait()) {
      // hooray!
      return true;
    }
    // The pause instruction is the polite way to spin, but it doesn't
    // actually affect correctness to omit it if we don't have it.
    // Pausing donates the full capabilities of the current core to
    // its other hyperthreads for a dozen cycles or so
    asm_volatile_pause();
  }

  return false;
}

template<typename Rep , typename Period >

bool folly::fibers::Baton::timed_wait ( const std::chrono::duration< Rep, Period > &  timeout )

inline

Alias to try_wait_for. Deprecated.

Definition at line 170 of file Baton.h.

References try_wait_for().

                                                                 {
    return try_wait_for(timeout);
  }

template<typename Rep , typename Period , typename F >

bool folly::fibers::Baton::timed_wait ( const std::chrono::duration< Rep, Period > &  timeout, F &&  mainContextFunc  )

inline

Alias to try_wait_for. Deprecated.

Definition at line 176 of file Baton.h.

References try_wait_for().

                           {
    return try_wait_for(timeout, static_cast<F&&>(mainContextFunc));
  }

template<typename Clock , typename Duration >

bool folly::fibers::Baton::timed_wait ( const std::chrono::time_point< Clock, Duration > &  deadline )

inline

Alias to try_wait_until. Deprecated.

Definition at line 184 of file Baton.h.

References try_wait_until().

                                                                        {
    return try_wait_until(deadline);
  }

template<typename Clock , typename Duration , typename F >

bool folly::fibers::Baton::timed_wait ( const std::chrono::time_point< Clock, Duration > &  deadline, F &&  mainContextFunc  )

inline

Alias to try_wait_until. Deprecated.

Definition at line 190 of file Baton.h.

References folly::fibers::Baton::Waiter::post(), reset(), and try_wait_until().

                           {
    return try_wait_until(deadline, static_cast<F&&>(mainContextFunc));
  }

bool folly::fibers::Baton::timedWaitThread ( TimeoutController::Duration  timeout )

private

Definition at line 113 of file Baton.cpp.

References futex, futex_, futexWaitUntil(), LIKELY, NO_WAITER, now(), POSTED, spinWaitForEarlyPost(), THREAD_WAITING, folly::detail::TIMEDOUT, TIMEOUT, uint32_t, and waiter_.

Referenced by Baton(), and try_wait_for().

                                                             {
  if (spinWaitForEarlyPost()) {
    assert(waiter_.load(std::memory_order_acquire) == POSTED);
    return true;
  }

  auto waiter = waiter_.load();

  if (LIKELY(
          waiter == NO_WAITER &&
          waiter_.compare_exchange_strong(waiter, THREAD_WAITING))) {
    auto deadline = TimeoutController::Clock::now() + timeout;
    do {
      auto* futex = &futex_.futex;
      const auto wait_rv =
          futexWaitUntil(futex, uint32_t(THREAD_WAITING), deadline);
      if (wait_rv == folly::detail::FutexResult::TIMEDOUT) {
        return false;
      }
      waiter = waiter_.load(std::memory_order_relaxed);
    } while (waiter == THREAD_WAITING);
  }

  if (LIKELY(waiter == POSTED)) {
    return true;
  }

  // Handle errors
  if (waiter == TIMEOUT) {
    throw std::logic_error("Thread baton can't have timeout status");
  }
  if (waiter == THREAD_WAITING) {
    throw std::logic_error("Other thread is already waiting on this baton");
  }
  throw std::logic_error("Other waiter is already waiting on this baton");
}

bool folly::fibers::Baton::try_wait

(

)

Checks if the baton has been posted without blocking.

Returns

true iff the baton has been posted.

Definition at line 174 of file Baton.cpp.

References ready().

Referenced by ready(), spinWaitForEarlyPost(), TEST(), and wait().

                     {
  return ready();
}

template<typename Rep , typename Period >

bool folly::fibers::Baton::try_wait_for ( const std::chrono::duration< Rep, Period > &  timeout )

inline

Puts active fiber to sleep. Returns when post is called or the timeout expires.

Parameters

timeout

Baton will be automatically awaken if timeout expires

Returns

true if was posted, false if timeout expired

Definition at line 105 of file Baton.h.

References folly::detail::timeout.

Referenced by TEST(), folly::fibers::TimedMutex::timed_lock(), timed_wait(), and try_wait_until().

                                                                   {
    return try_wait_for(timeout, [] {});
  }

template<typename Rep , typename Period , typename F >

bool folly::fibers::Baton::try_wait_for	(	const std::chrono::duration< Rep, Period > &	timeout,
		F &&	mainContextFunc
	)

Puts active fiber to sleep. Returns when post is called or the timeout expires.

Parameters

timeout	Baton will be automatically awaken if timeout expires
mainContextFunc	this function is immediately executed on the main context.

Returns

true if was posted, false if timeout expired

Definition at line 75 of file Baton-inl.h.

References folly::fibers::FiberManager::getFiberManagerUnsafe(), POSTED, timedWaitThread(), TIMEOUT, waiter_, and waitFiber().

                         {
  auto fm = FiberManager::getFiberManagerUnsafe();

  if (!fm || !fm->activeFiber_) {
    mainContextFunc();
    return timedWaitThread(timeout);
  }

  auto& baton = *this;
  bool canceled = false;
  auto timeoutFunc = [&baton, &canceled]() mutable {
    baton.postHelper(TIMEOUT);
    canceled = true;
  };

  auto id =
      fm->timeoutManager_->registerTimeout(std::ref(timeoutFunc), timeout);

  waitFiber(*fm, static_cast<F&&>(mainContextFunc));

  auto posted = waiter_ == POSTED;

  if (!canceled) {
    fm->timeoutManager_->cancel(id);
  }

  return posted;
}

template<typename Clock , typename Duration , typename F >

bool folly::fibers::Baton::try_wait_for	(	const std::chrono::time_point< Clock, Duration > &	deadline,
		F &&	mainContextFunc
	)

Puts active fiber to sleep. Returns when post is called or the deadline expires.

Parameters

timeout	Baton will be automatically awaken if deadline expires
mainContextFunc	this function is immediately executed on the main context.

Returns

true if was posted, false if timeout expired

template<typename Clock , typename Duration >

bool folly::fibers::Baton::try_wait_until ( const std::chrono::time_point< Clock, Duration > &  deadline )

inline

Puts active fiber to sleep. Returns when post is called or the deadline expires.

Parameters

timeout

Baton will be automatically awaken if deadline expires

Returns

true if was posted, false if timeout expired

Definition at line 133 of file Baton.h.

References try_wait_for().

Referenced by timed_wait().

                                                            {
    return try_wait_until(deadline, [] {});
  }

template<typename Clock , typename Duration , typename F >

bool folly::fibers::Baton::try_wait_until	(	const std::chrono::time_point< Clock, Duration > &	deadline,
		F &&	mainContextFunc
	)

Puts active fiber to sleep. Returns when post is called or the deadline expires.

Parameters

timeout	Baton will be automatically awaken if deadline expires
mainContextFunc	this function is immediately executed on the main context.

Returns

true if was posted, false if timeout expired

Definition at line 107 of file Baton-inl.h.

References LIKELY, now(), and try_wait_for().

                         {
  auto now = Clock::now();

  if (LIKELY(now <= deadline)) {
    return try_wait_for(deadline - now, static_cast<F&&>(mainContextFunc));
  } else {
    return try_wait_for(Duration{}, static_cast<F&&>(mainContextFunc));
  }
}

void folly::fibers::Baton::wait

(

)

Puts active fiber to sleep. Returns when post is called.

Definition at line 45 of file Baton.cpp.

Referenced by folly::fibers::forEach(), folly::fibers::TimedMutex::lock(), ready(), TEST(), folly::coro::detail::BlockingWaitPromiseBase::wait(), wait(), and folly::fibers::Semaphore::waitSlow().

                 {
  wait([]() {});
}

void folly::fibers::Baton::wait

(

TimeoutHandler &

timeoutHandler

)

Put active fiber to sleep indefinitely. However, timeoutHandler may be used elsewhere on the same thread in order to schedule a wakeup for the active fiber. Users of timeoutHandler must be on the same thread as the active fiber and may only schedule one timeout, which must occur after the active fiber calls wait.

Definition at line 49 of file Baton.cpp.

References folly::fibers::Baton::TimeoutHandler::cancelTimeout(), folly::fibers::Baton::TimeoutHandler::fiberManager_, folly::fibers::FiberManager::getFiberManagerUnsafe(), postHelper(), TIMEOUT, folly::fibers::Baton::TimeoutHandler::timeoutFunc_, folly::fibers::Baton::TimeoutHandler::timeoutPtr_, try_wait(), and wait().

                                               {
  auto timeoutFunc = [this, &timeoutHandler] {
    if (!try_wait()) {
      postHelper(TIMEOUT);
    }
    timeoutHandler.timeoutPtr_ = 0;
  };
  timeoutHandler.timeoutFunc_ = std::ref(timeoutFunc);
  timeoutHandler.fiberManager_ = FiberManager::getFiberManagerUnsafe();
  wait();
  timeoutHandler.cancelTimeout();
}

template<typename F >

void folly::fibers::Baton::wait

(

F &&

mainContextFunc

)

Puts active fiber to sleep. Returns when post is called.

Parameters

mainContextFunc

this function is immediately executed on the main context.

Definition at line 50 of file Baton-inl.h.

References folly::fibers::FiberManager::getFiberManagerUnsafe(), waitFiber(), and waitThread().

                                    {
  auto fm = FiberManager::getFiberManagerUnsafe();
  if (!fm || !fm->activeFiber_) {
    mainContextFunc();
    return waitThread();
  }

  return waitFiber(*fm, std::forward<F>(mainContextFunc));
}

template<typename F >

void folly::fibers::Baton::waitFiber ( FiberManager &  fm, F &&  mainContextFunc  )

inlineprivate

Definition at line 61 of file Baton-inl.h.

References folly::fibers::FiberManager::activeFiber_, folly::fibers::FiberManager::awaitFunc_, folly::fibers::Fiber::AWAITING, f, folly::fibers::Fiber::preempt(), folly::fibers::Baton::FiberWaiter::setFiber(), and setWaiter().

Referenced by Baton(), try_wait_for(), and wait().

                                                           {
  FiberWaiter waiter;
  auto f = [this, &mainContextFunc, &waiter](Fiber& fiber) mutable {
    waiter.setFiber(fiber);
    setWaiter(waiter);

    mainContextFunc();
  };

  fm.awaitFunc_ = std::ref(f);
  fm.activeFiber_->preempt(Fiber::AWAITING);
}

void folly::fibers::Baton::waitThread ( )

private

Definition at line 62 of file Baton.cpp.

References futex_, folly::detail::MemoryIdler::futexWait(), LIKELY, NO_WAITER, POSTED, spinWaitForEarlyPost(), THREAD_WAITING, TIMEOUT, uint32_t, and waiter_.

Referenced by Baton(), and wait().

                       {
  if (spinWaitForEarlyPost()) {
    assert(waiter_.load(std::memory_order_acquire) == POSTED);
    return;
  }

  auto waiter = waiter_.load();

  if (LIKELY(
          waiter == NO_WAITER &&
          waiter_.compare_exchange_strong(waiter, THREAD_WAITING))) {
    do {
      folly::detail::MemoryIdler::futexWait(
          futex_.futex, uint32_t(THREAD_WAITING));
      waiter = waiter_.load(std::memory_order_acquire);
    } while (waiter == THREAD_WAITING);
  }

  if (LIKELY(waiter == POSTED)) {
    return;
  }

  // Handle errors
  if (waiter == TIMEOUT) {
    throw std::logic_error("Thread baton can't have timeout status");
  }
  if (waiter == THREAD_WAITING) {
    throw std::logic_error("Other thread is already waiting on this baton");
  }
  throw std::logic_error("Other waiter is already waiting on this baton");
}

Member Data Documentation

union { ... }

int32_t folly::fibers::Baton::_unused_packing

Definition at line 282 of file Baton.h.

folly::detail::Futex folly::fibers::Baton::futex {}

Definition at line 281 of file Baton.h.

Referenced by postThread(), and timedWaitThread().

struct { ... } folly::fibers::Baton::futex_

Referenced by Baton(), postThread(), timedWaitThread(), and waitThread().

constexpr intptr_t folly::fibers::Baton::NO_WAITER = 0

staticprivate

Definition at line 273 of file Baton.h.

Referenced by postHelper(), reset(), setWaiter(), timedWaitThread(), and waitThread().

constexpr intptr_t folly::fibers::Baton::POSTED = -1

staticprivate

Definition at line 274 of file Baton.h.

Referenced by Baton(), post(), postHelper(), postThread(), ready(), setWaiter(), timedWaitThread(), try_wait_for(), and waitThread().

constexpr intptr_t folly::fibers::Baton::THREAD_WAITING = -3

staticprivate

Definition at line 276 of file Baton.h.

Referenced by Baton(), postHelper(), postThread(), timedWaitThread(), and waitThread().

constexpr intptr_t folly::fibers::Baton::TIMEOUT = -2

staticprivate

Definition at line 275 of file Baton.h.

Referenced by Baton(), postHelper(), setWaiter(), timedWaitThread(), try_wait_for(), wait(), and waitThread().

std::atomic<intptr_t> folly::fibers::Baton::waiter_

Definition at line 279 of file Baton.h.

Referenced by Baton(), postHelper(), postThread(), ready(), reset(), setWaiter(), timedWaitThread(), try_wait_for(), and waitThread().

---

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

• proxygen/folly/folly/fibers/Baton.h
• proxygen/folly/folly/fibers/Baton-inl.h
• proxygen/folly/folly/fibers/Baton.cpp