folly/io/async/EventHandler.h

   1 /*
   2  * Copyright 2016 Facebook, Inc.
   3  *
   4  * Licensed to the Apache Software Foundation (ASF) under one
   5  * or more contributor license agreements. See the NOTICE file
   6  * distributed with this work for additional information
   7  * regarding copyright ownership. The ASF licenses this file
   8  * to you under the Apache License, Version 2.0 (the
   9  * "License"); you may not use this file except in compliance
  10  * with the License. You may obtain a copy of the License at
  11  *
  12  *   http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  * KIND, either express or implied. See the License for the
  18  * specific language governing permissions and limitations
  19  * under the License.
  20  */
  21 #pragma once
  22
  23 #include <glog/logging.h>
  24 #include <folly/io/async/EventUtil.h>
  25 #include <folly/portability/Event.h>
  26 #include <boost/noncopyable.hpp>
  27 #include <stddef.h>
  28
  29 namespace folly {
  30
  31 class EventBase;
  32
  33 /**
  34  * The EventHandler class is used to asynchronously wait for events on a file
  35  * descriptor.
  36  *
  37  * Users that wish to wait on I/O events should derive from EventHandler and
  38  * implement the handlerReady() method.
  39  */
  40 class EventHandler : private boost::noncopyable {
  41  public:
  42   enum EventFlags {
  43     NONE = 0,
  44     READ = EV_READ,
  45     WRITE = EV_WRITE,
  46     READ_WRITE = (READ | WRITE),
  47     PERSIST = EV_PERSIST
  48   };
  49
  50   /**
  51    * Create a new EventHandler object.
  52    *
  53    * @param eventBase  The EventBase to use to drive this event handler.
  54    *                   This may be nullptr, in which case the EventBase must be
  55    *                   set separately using initHandler() or attachEventBase()
  56    *                   before the handler can be registered.
  57    * @param fd         The file descriptor that this EventHandler will
  58    *                   monitor.  This may be -1, in which case the file
  59    *                   descriptor must be set separately using initHandler() or
  60    *                   changeHandlerFD() before the handler can be registered.
  61    */
  62   explicit EventHandler(EventBase* eventBase = nullptr, int fd = -1);
  63
  64   /**
  65    * EventHandler destructor.
  66    *
  67    * The event will be automatically unregistered if it is still registered.
  68    */
  69   virtual ~EventHandler();
  70
  71   /**
  72    * handlerReady() is invoked when the handler is ready.
  73    *
  74    * @param events  A bitset indicating the events that are ready.
  75    */
  76   virtual void handlerReady(uint16_t events) noexcept = 0;
  77
  78   /**
  79    * Register the handler.
  80    *
  81    * If the handler is already registered, the registration will be updated
  82    * to wait on the new set of events.
  83    *
  84    * @param events   A bitset specifying the events to monitor.
  85    *                 If the PERSIST bit is set, the handler will remain
  86    *                 registered even after handlerReady() is called.
  87    *
  88    * @return Returns true if the handler was successfully registered,
  89    *         or false if an error occurred.  After an error, the handler is
  90    *         always unregistered, even if it was already registered prior to
  91    *         this call to registerHandler().
  92    */
  93   bool registerHandler(uint16_t events) {
  94     return registerImpl(events, false);
  95   }
  96
  97   /**
  98    * Unregister the handler, if it is registered.
  99    */
 100   void unregisterHandler();
 101
 102   /**
 103    * Returns true if the handler is currently registered.
 104    */
 105   bool isHandlerRegistered() const {
 106     return EventUtil::isEventRegistered(&event_);
 107   }
 108
 109   /**
 110    * Attach the handler to a EventBase.
 111    *
 112    * This may only be called if the handler is not currently attached to a
 113    * EventBase (either by using the default constructor, or by calling
 114    * detachEventBase()).
 115    *
 116    * This method must be invoked in the EventBase's thread.
 117    */
 118   void attachEventBase(EventBase* eventBase);
 119
 120   /**
 121    * Detach the handler from its EventBase.
 122    *
 123    * This may only be called when the handler is not currently registered.
 124    * Once detached, the handler may not be registered again until it is
 125    * re-attached to a EventBase by calling attachEventBase().
 126    *
 127    * This method must be called from the current EventBase's thread.
 128    */
 129   void detachEventBase();
 130
 131   /**
 132    * Change the file descriptor that this handler is associated with.
 133    *
 134    * This may only be called when the handler is not currently registered.
 135    */
 136   void changeHandlerFD(int fd);
 137
 138   /**
 139    * Attach the handler to a EventBase, and change the file descriptor.
 140    *
 141    * This method may only be called if the handler is not currently attached to
 142    * a EventBase.  This is primarily intended to be used to initialize
 143    * EventHandler objects created using the default constructor.
 144    */
 145   void initHandler(EventBase* eventBase, int fd);
 146
 147   /**
 148    * Return the set of events that we're currently registered for.
 149    */
 150   uint16_t getRegisteredEvents() const {
 151     return (isHandlerRegistered()) ?
 152       event_.ev_events : 0;
 153   }
 154
 155   /**
 156    * Register the handler as an internal event.
 157    *
 158    * This event will not count as an active event for determining if the
 159    * EventBase loop has more events to process.  The EventBase loop runs
 160    * only as long as there are active EventHandlers, however "internal" event
 161    * handlers are not counted.  Therefore this event handler will not prevent
 162    * EventBase loop from exiting with no more work to do if there are no other
 163    * non-internal event handlers registered.
 164    *
 165    * This is intended to be used only in very rare cases by the internal
 166    * EventBase code.  This API is not guaranteed to remain stable or portable
 167    * in the future.
 168    */
 169   bool registerInternalHandler(uint16_t events) {
 170     return registerImpl(events, true);
 171   }
 172
 173   bool isPending() const;
 174
 175  private:
 176   bool registerImpl(uint16_t events, bool internal);
 177   void ensureNotRegistered(const char* fn);
 178
 179   void setEventBase(EventBase* eventBase);
 180
 181   static void libeventCallback(libevent_fd_t fd, short events, void* arg);
 182
 183   struct event event_;
 184   EventBase* eventBase_;
 185 };
 186
 187 } // folly