folly/io/async/EventHandler.h

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