folly::EventHandler Class Reference

#include <EventHandler.h>

Inheritance diagram for folly::EventHandler:

Public Types
enum	EventFlags {   NONE = 0, READ = EV_READ, WRITE = EV_WRITE, READ_WRITE = (READ | WRITE),   PERSIST = EV_PERSIST }

Public Member Functions
	EventHandler (EventBase *eventBase, int fd)
	EventHandler (EventBase *eventBase=nullptr, NetworkSocket fd=NetworkSocket())
virtual	~EventHandler ()
virtual void	handlerReady (uint16_t events) noexcept=0
bool	registerHandler (uint16_t events)
void	unregisterHandler ()
bool	isHandlerRegistered () const
void	attachEventBase (EventBase *eventBase)
void	detachEventBase ()
void	changeHandlerFD (int fd)
void	changeHandlerFD (NetworkSocket fd)
void	initHandler (EventBase *eventBase, int fd)
void	initHandler (EventBase *eventBase, NetworkSocket fd)
uint16_t	getRegisteredEvents () const
bool	registerInternalHandler (uint16_t events)
bool	isPending () const

Private Member Functions
bool	registerImpl (uint16_t events, bool internal)
void	ensureNotRegistered (const char *fn)
void	setEventBase (EventBase *eventBase)

Static Private Member Functions
static void	libeventCallback (libevent_fd_t fd, short events, void *arg)

Private Attributes
struct event	event_
EventBase *	eventBase_

Detailed Description

The EventHandler class is used to asynchronously wait for events on a file descriptor.

Users that wish to wait on I/O events should derive from EventHandler and implement the handlerReady() method.

Definition at line 39 of file EventHandler.h.

Member Enumeration Documentation

enum folly::EventHandler::EventFlags

Enumerator
NONE
READ
WRITE
READ_WRITE
PERSIST

Definition at line 41 of file EventHandler.h.

                  {
    NONE = 0,
    READ = EV_READ,
    WRITE = EV_WRITE,
    READ_WRITE = (READ | WRITE),
    PERSIST = EV_PERSIST,
// Temporary flag until EPOLLPRI is upstream on libevent.
#ifdef EV_PRI
    PRI = EV_PRI,
#endif
  };

Constructor & Destructor Documentation

folly::EventHandler::EventHandler ( EventBase *  eventBase, int  fd  )

inlineexplicit

Create a new EventHandler object.

Parameters

eventBase	The EventBase to use to drive this event handler. This may be nullptr, in which case the EventBase must be set separately using initHandler() or attachEventBase() before the handler can be registered.
fd	The file descriptor that this EventHandler will monitor. This may be -1, in which case the file descriptor must be set separately using initHandler() or changeHandlerFD() before the handler can be registered.

Definition at line 65 of file EventHandler.h.

References handlerReady(), folly::pushmi::__adl::noexcept(), uint16_t, and ~EventHandler().

      : EventHandler(eventBase, NetworkSocket::fromFd(fd)) {}

folly::EventHandler::EventHandler ( EventBase *  eventBase = nullptr, NetworkSocket  fd = NetworkSocket()  )

explicit

Definition at line 25 of file EventHandler.cpp.

References event_, eventBase_, folly::folly_event_set(), libeventCallback(), setEventBase(), and folly::NetworkSocket::toFd().

                                                                 {
  folly_event_set(&event_, fd.toFd(), 0, &EventHandler::libeventCallback, this);
  if (eventBase != nullptr) {
    setEventBase(eventBase);
  } else {
    // Callers must set the EventBase and fd before using this timeout.
    // Set event_->ev_base to nullptr to ensure that this happens.
    // (otherwise libevent will initialize it to the "default" event_base)
    event_.ev_base = nullptr;
    eventBase_ = nullptr;
  }
}

folly::EventHandler::~EventHandler ( )

virtual

EventHandler destructor.

The event will be automatically unregistered if it is still registered.

Definition at line 38 of file EventHandler.cpp.

References unregisterHandler().

Referenced by EventHandler().

                            {
  unregisterHandler();
}

Member Function Documentation

void folly::EventHandler::attachEventBase

(

EventBase *

eventBase

)

Attach the handler to a EventBase.

This may only be called if the handler is not currently attached to a EventBase (either by using the default constructor, or by calling detachEventBase()).

This method must be invoked in the EventBase's thread.

Definition at line 109 of file EventHandler.cpp.

References folly::EventBase::dcheckIsInEventBaseThread(), event_, isHandlerRegistered(), and setEventBase().

Referenced by folly::AsyncUDPSocket::attachEventBase(), folly::AsyncSocket::attachEventBase(), and isHandlerRegistered().

                                                       {
  // attachEventBase() may only be called on detached handlers
  assert(event_.ev_base == nullptr);
  assert(!isHandlerRegistered());
  // This must be invoked from the EventBase's thread
  eventBase->dcheckIsInEventBaseThread();

  setEventBase(eventBase);
}

void folly::EventHandler::changeHandlerFD ( int  fd )

inline

Change the file descriptor that this handler is associated with.

This may only be called when the handler is not currently registered.

Definition at line 143 of file EventHandler.h.

References folly::NetworkSocket::fromFd().

Referenced by folly::AsyncUDPSocket::bind(), folly::AsyncPipeReader::close(), folly::AsyncPipeWriter::closeNow(), folly::AsyncSocket::closeNow(), folly::AsyncSocket::connect(), folly::AsyncSocket::detachFd(), folly::AsyncSocket::handleWrite(), folly::AsyncUDPSocket::setFD(), and folly::AsyncSocket::startFail().

                               {
    changeHandlerFD(NetworkSocket::fromFd(fd));
  }

void folly::EventHandler::changeHandlerFD

(

NetworkSocket

fd

)

Definition at line 124 of file EventHandler.cpp.

References ensureNotRegistered(), event_, folly::folly_event_set(), libeventCallback(), and folly::NetworkSocket::toFd().

                                                   {
  ensureNotRegistered(__func__);
  // event_set() resets event_base.ev_base, so manually restore it afterwards
  struct event_base* evb = event_.ev_base;
  folly_event_set(&event_, fd.toFd(), 0, &EventHandler::libeventCallback, this);
  event_.ev_base = evb; // don't use event_base_set(), since evb may be nullptr
}

void folly::EventHandler::detachEventBase

(

)

Detach the handler from its EventBase.

This may only be called when the handler is not currently registered. Once detached, the handler may not be registered again until it is re-attached to a EventBase by calling attachEventBase().

This method must be called from the current EventBase's thread.

Definition at line 119 of file EventHandler.cpp.

References ensureNotRegistered(), and event_.

Referenced by folly::AsyncUDPSocket::detachEventBase(), folly::AsyncSocket::detachEventBase(), and isHandlerRegistered().

                                   {
  ensureNotRegistered(__func__);
  event_.ev_base = nullptr;
}

void folly::EventHandler::ensureNotRegistered ( const char *  fn )

private

Definition at line 138 of file EventHandler.cpp.

References isHandlerRegistered().

Referenced by changeHandlerFD(), detachEventBase(), initHandler(), and registerInternalHandler().

                                                     {
  // Neither the EventBase nor file descriptor may be changed while the
  // handler is registered.  Treat it as a programmer bug and abort the program
  // if this requirement is violated.
  if (isHandlerRegistered()) {
    LOG(ERROR) << fn << " called on registered handler; aborting";
    abort();
  }
}

uint16_t folly::EventHandler::getRegisteredEvents ( ) const

inline

Return the set of events that we're currently registered for.

Definition at line 165 of file EventHandler.h.

References event_, isHandlerRegistered(), and uint16_t.

                                       {
    return (isHandlerRegistered()) ? uint16_t(event_.ev_events) : 0u;
  }

virtual void folly::EventHandler::handlerReady ( uint16_t  events )

pure virtualnoexcept

handlerReady() is invoked when the handler is ready.

Parameters

events

A bitset indicating the events that are ready.

Implemented in PipeHandler, TerminateTestCallback, folly::AsyncSocket::IoHandler, folly::AsyncServerSocket::ServerEventHandler, PartialWriteHandler, PartialReadHandler, folly::AsyncUDPSocket, folly::NotificationQueue< MessageT >::Consumer, folly::AsyncPipeWriter, TestHandler, folly::AsyncPipeReader, fizz::tool::TerminalInputHandler, and EventHandlerMock.

Referenced by EventHandler(), and libeventCallback().

void folly::EventHandler::initHandler ( EventBase *  eventBase, int  fd  )

inline

Attach the handler to a EventBase, and change the file descriptor.

This method may only be called if the handler is not currently attached to a EventBase. This is primarily intended to be used to initialize EventHandler objects created using the default constructor.

Definition at line 156 of file EventHandler.h.

References folly::NetworkSocket::fromFd().

                                                 {
    initHandler(eventBase, NetworkSocket::fromFd(fd));
  }

void folly::EventHandler::initHandler	(	EventBase *	eventBase,
		NetworkSocket	fd
	)

Definition at line 132 of file EventHandler.cpp.

References ensureNotRegistered(), event_, folly::folly_event_set(), libeventCallback(), setEventBase(), and folly::NetworkSocket::toFd().

                                                                     {
  ensureNotRegistered(__func__);
  folly_event_set(&event_, fd.toFd(), 0, &EventHandler::libeventCallback, this);
  setEventBase(eventBase);
}

bool folly::EventHandler::isHandlerRegistered ( ) const

inline

Returns true if the handler is currently registered.

Definition at line 112 of file EventHandler.h.

References attachEventBase(), detachEventBase(), event_, and folly::EventUtil::isEventRegistered().

Referenced by attachEventBase(), folly::AsyncPipeWriter::closeOnEmpty(), ensureNotRegistered(), getRegisteredEvents(), registerImpl(), folly::AsyncPipeReader::setReadCB(), unregisterHandler(), and folly::AsyncPipeWriter::write().

                                   {
    return EventUtil::isEventRegistered(&event_);
  }

bool folly::EventHandler::isPending

(

)

const

Definition at line 173 of file EventHandler.cpp.

References event_, and folly::event_ref_flags().

Referenced by folly::AsyncSocket::isPending(), and registerInternalHandler().

                                   {
  if (event_ref_flags(&event_) & EVLIST_ACTIVE) {
    if (event_.ev_res & EV_READ) {
      return true;
    }
  }
  return false;
}

void folly::EventHandler::libeventCallback ( libevent_fd_t  fd, short  events, void *  arg  )

staticprivate

Definition at line 148 of file EventHandler.cpp.

References folly::EventBase::bumpHandlingTime(), event_, eventBase_, folly::EventBase::getExecutionObserver(), handler(), handlerReady(), folly::ExecutionObserver::starting(), and uint16_t.

Referenced by changeHandlerFD(), EventHandler(), initHandler(), registerImpl(), and registerInternalHandler().

                                                                             {
  EventHandler* handler = reinterpret_cast<EventHandler*>(arg);
  assert(fd == handler->event_.ev_fd);
  (void)fd; // prevent unused variable warnings

  auto observer = handler->eventBase_->getExecutionObserver();
  if (observer) {
    observer->starting(reinterpret_cast<uintptr_t>(handler));
  }

  // this can't possibly fire if handler->eventBase_ is nullptr
  handler->eventBase_->bumpHandlingTime();

  handler->handlerReady(uint16_t(events));

  if (observer) {
    observer->stopped(reinterpret_cast<uintptr_t>(handler));
  }
}

bool folly::EventHandler::registerHandler ( uint16_t  events )

inline

Register the handler.

If the handler is already registered, the registration will be updated to wait on the new set of events.

Parameters

events

A bitset specifying the events to monitor. If the PERSIST bit is set, the handler will remain registered even after handlerReady() is called.

Returns

Returns true if the handler was successfully registered, or false if an error occurred. After an error, the handler is always unregistered, even if it was already registered prior to this call to registerHandler().

Definition at line 100 of file EventHandler.h.

References registerImpl(), and unregisterHandler().

Referenced by folly::AsyncUDPSocket::detachEventBase(), folly::AsyncPipeWriter::handleWrite(), folly::AsyncSocket::registerForConnectEvents(), folly::AsyncPipeReader::setReadCB(), fizz::tool::TerminalInputHandler::TerminalInputHandler(), TEST(), TEST_F(), folly::AsyncSocket::updateEventRegistration(), and folly::AsyncUDPSocket::updateRegistration().

                                        {
    return registerImpl(events, false);
  }

bool folly::EventHandler::registerImpl ( uint16_t  events, bool  internal  )

private

Definition at line 42 of file EventHandler.cpp.

References folly::errnoStr(), event_, folly::event_ref_flags(), isHandlerRegistered(), and libeventCallback().

Referenced by registerHandler(), and registerInternalHandler().

                                                              {
  assert(event_.ev_base != nullptr);

  // We have to unregister the event before we can change the event flags
  if (isHandlerRegistered()) {
    // If the new events are the same are the same as the already registered
    // flags, we don't have to do anything.  Just return.
    auto flags = event_ref_flags(&event_);
    if (events == event_.ev_events &&
        static_cast<bool>(flags & EVLIST_INTERNAL) == internal) {
      return true;
    }

    event_del(&event_);
  }

  // Update the event flags
  // Unfortunately, event_set() resets the event_base, so we have to remember
  // it before hand, then pass it back into event_base_set() afterwards
  struct event_base* evb = event_.ev_base;
  event_set(
      &event_,
      event_.ev_fd,
      short(events),
      &EventHandler::libeventCallback,
      this);
  event_base_set(evb, &event_);

  // Set EVLIST_INTERNAL if this is an internal event
  if (internal) {
    event_ref_flags(&event_) |= EVLIST_INTERNAL;
  }

  // Add the event.
  //
  // Although libevent allows events to wait on both I/O and a timeout,
  // we intentionally don't allow an EventHandler to also use a timeout.
  // Callers must maintain a separate AsyncTimeout object if they want a
  // timeout.
  //
  // Otherwise, it is difficult to handle persistent events properly.  (The I/O
  // event and timeout may both fire together the same time around the event
  // loop.  Normally we would want to inform the caller of the I/O event first,
  // then the timeout.  However, it is difficult to do this properly since the
  // I/O callback could delete the EventHandler.)  Additionally, if a caller
  // uses the same struct event for both I/O and timeout, and they just want to
  // reschedule the timeout, libevent currently makes an epoll_ctl() call even
  // if the I/O event flags haven't changed.  Using a separate event struct is
  // therefore slightly more efficient in this case (although it does take up
  // more space).
  if (event_add(&event_, nullptr) < 0) {
    LOG(ERROR) << "EventBase: failed to register event handler for fd "
               << event_.ev_fd << ": " << errnoStr(errno);
    // Call event_del() to make sure the event is completely uninstalled
    event_del(&event_);
    return false;
  }

  return true;
}

bool folly::EventHandler::registerInternalHandler ( uint16_t  events )

inline

Register the handler as an internal event.

This event will not count as an active event for determining if the EventBase loop has more events to process. The EventBase loop runs only as long as there are active EventHandlers, however "internal" event handlers are not counted. Therefore this event handler will not prevent EventBase loop from exiting with no more work to do if there are no other non-internal event handlers registered.

This is intended to be used only in very rare cases by the internal EventBase code. This API is not guaranteed to remain stable or portable in the future.

Definition at line 183 of file EventHandler.h.

References ensureNotRegistered(), isPending(), libeventCallback(), registerImpl(), setEventBase(), and uint16_t.

                                                {
    return registerImpl(events, true);
  }

void folly::EventHandler::setEventBase ( EventBase *  eventBase )

private

Definition at line 168 of file EventHandler.cpp.

References event_, eventBase_, and folly::EventBase::getLibeventBase().

Referenced by attachEventBase(), EventHandler(), initHandler(), and registerInternalHandler().

                                                    {
  event_base_set(eventBase->getLibeventBase(), &event_);
  eventBase_ = eventBase;
}

void folly::EventHandler::unregisterHandler

(

)

Unregister the handler, if it is registered.

Definition at line 103 of file EventHandler.cpp.

References event_, and isHandlerRegistered().

Referenced by folly::AsyncPipeReader::close(), folly::AsyncUDPSocket::close(), folly::AsyncPipeWriter::closeNow(), folly::AsyncSocket::detachEventBase(), folly::AsyncPipeReader::handlerReady(), folly::AsyncPipeWriter::handleWrite(), registerHandler(), folly::AsyncPipeReader::setReadCB(), folly::AsyncSocket::startFail(), TEST(), TEST_F(), folly::AsyncSocket::updateEventRegistration(), and ~EventHandler().

                                     {
  if (isHandlerRegistered()) {
    event_del(&event_);
  }
}

Member Data Documentation

struct event folly::EventHandler::event_

private

Definition at line 197 of file EventHandler.h.

Referenced by attachEventBase(), changeHandlerFD(), detachEventBase(), EventHandler(), getRegisteredEvents(), initHandler(), isHandlerRegistered(), isPending(), libeventCallback(), registerImpl(), setEventBase(), and unregisterHandler().

EventBase* folly::EventHandler::eventBase_

private

Definition at line 198 of file EventHandler.h.

Referenced by EventHandler(), libeventCallback(), and setEventBase().

---

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

• proxygen/folly/folly/io/async/EventHandler.h
• proxygen/folly/folly/io/async/EventHandler.cpp