folly/io/async/DelayedDestruction.h

   1 /*
   2  * Copyright 2015 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #pragma once
  18
  19 #include <boost/noncopyable.hpp>
  20 #include <inttypes.h>
  21 #include <assert.h>
  22
  23 namespace folly {
  24
  25 /**
  26  * DelayedDestruction is a helper class to ensure objects are not deleted
  27  * while they still have functions executing in a higher stack frame.
  28  *
  29  * This is useful for objects that invoke callback functions, to ensure that a
  30  * callback does not destroy the calling object.
  31  *
  32  * Classes needing this functionality should:
  33  * - derive from DelayedDestruction
  34  * - make their destructor private or protected, so it cannot be called
  35  *   directly
  36  * - create a DestructorGuard object on the stack in each public method that
  37  *   may invoke a callback
  38  *
  39  * DelayedDestruction does not perform any locking.  It is intended to be used
  40  * only from a single thread.
  41  */
  42 class DelayedDestruction : private boost::noncopyable {
  43  public:
  44   /**
  45    * Helper class to allow DelayedDestruction classes to be used with
  46    * std::shared_ptr.
  47    *
  48    * This class can be specified as the destructor argument when creating the
  49    * shared_ptr, and it will destroy the guarded class properly when all
  50    * shared_ptr references are released.
  51    */
  52   class Destructor {
  53    public:
  54     void operator()(DelayedDestruction* dd) const {
  55       dd->destroy();
  56     }
  57   };
  58
  59   /**
  60    * destroy() requests destruction of the object.
  61    *
  62    * This method will destroy the object after it has no more functions running
  63    * higher up on the stack.  (i.e., No more DestructorGuard objects exist for
  64    * this object.)  This method must be used instead of the destructor.
  65    */
  66   virtual void destroy() {
  67     // If guardCount_ is not 0, just set destroyPending_ to delay
  68     // actual destruction.
  69     if (guardCount_ != 0) {
  70       destroyPending_ = true;
  71     } else {
  72       destroyNow(false);
  73     }
  74   }
  75
  76   /**
  77    * Classes should create a DestructorGuard object on the stack in any
  78    * function that may invoke callback functions.
  79    *
  80    * The DestructorGuard prevents the guarded class from being destroyed while
  81    * it exists.  Without this, the callback function could delete the guarded
  82    * object, causing problems when the callback function returns and the
  83    * guarded object's method resumes execution.
  84    */
  85   class DestructorGuard {
  86    public:
  87
  88     explicit DestructorGuard(DelayedDestruction* dd) : dd_(dd) {
  89       ++dd_->guardCount_;
  90       assert(dd_->guardCount_ > 0); // check for wrapping
  91     }
  92
  93     DestructorGuard(const DestructorGuard& dg) : dd_(dg.dd_) {
  94       ++dd_->guardCount_;
  95       assert(dd_->guardCount_ > 0); // check for wrapping
  96     }
  97
  98     ~DestructorGuard() {
  99       assert(dd_->guardCount_ > 0);
 100       --dd_->guardCount_;
 101       if (dd_->guardCount_ == 0 && dd_->destroyPending_) {
 102         dd_->destroyPending_ = false;
 103         dd_->destroyNow(true);
 104       }
 105     }
 106
 107    private:
 108     DelayedDestruction* dd_;
 109   };
 110
 111  protected:
 112   /**
 113    * destroyNow() is invoked to actually destroy the object, after destroy()
 114    * has been called and no more DestructorGuard objects exist.  By default it
 115    * calls "delete this", but subclasses may override this behavior.
 116    *
 117    * @param delayed  This parameter is true if destruction was delayed because
 118    *                 of a DestructorGuard object, or false if destroyNow() is
 119    *                 being called directly from destroy().
 120    */
 121   virtual void destroyNow(bool delayed) {
 122     delete this;
 123     (void)delayed; // prevent unused variable warnings
 124   }
 125
 126   DelayedDestruction()
 127     : guardCount_(0)
 128     , destroyPending_(false) {}
 129
 130   /**
 131    * Protected destructor.
 132    *
 133    * Making this protected ensures that users cannot delete DelayedDestruction
 134    * objects directly, and that everyone must use destroy() instead.
 135    * Subclasses of DelayedDestruction must also define their destructors as
 136    * protected or private in order for this to work.
 137    *
 138    * This also means that DelayedDestruction objects cannot be created
 139    * directly on the stack; they must always be dynamically allocated on the
 140    * heap.
 141    *
 142    * In order to use a DelayedDestruction object with a shared_ptr, create the
 143    * shared_ptr using a DelayedDestruction::Destructor as the second argument
 144    * to the shared_ptr constructor.
 145    */
 146   virtual ~DelayedDestruction() = default;
 147
 148   /**
 149    * Get the number of DestructorGuards currently protecting this object.
 150    *
 151    * This is primarily intended for debugging purposes, such as asserting
 152    * that an object has at least 1 guard.
 153    */
 154   uint32_t getDestructorGuardCount() const {
 155     return guardCount_;
 156   }
 157
 158  private:
 159   /**
 160    * guardCount_ is incremented by DestructorGuard, to indicate that one of
 161    * the DelayedDestruction object's methods is currently running.
 162    *
 163    * If destroy() is called while guardCount_ is non-zero, destruction will
 164    * be delayed until guardCount_ drops to 0.  This allows DelayedDestruction
 165    * objects to invoke callbacks without having to worry about being deleted
 166    * before the callback returns.
 167    */
 168   uint32_t guardCount_;
 169
 170   /**
 171    * destroyPending_ is set to true if destoy() is called while guardCount_ is
 172    * non-zero.
 173    *
 174    * If destroyPending_ is true, the object will be destroyed the next time
 175    * guardCount_ drops to 0.
 176    */
 177   bool destroyPending_;
 178 };
 179 } // folly