folly/io/async/EventHandler.h

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