folly/io/async/DelayedDestruction.h

   1 /*
   2  * Copyright 2017 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 <folly/io/async/DelayedDestructionBase.h>
  20
  21 #include <glog/logging.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 : public DelayedDestructionBase {
  43  public:
  44   /**
  45    * destroy() requests destruction of the object.
  46    *
  47    * This method will destroy the object after it has no more functions running
  48    * higher up on the stack.  (i.e., No more DestructorGuard objects exist for
  49    * this object.)  This method must be used instead of the destructor.
  50    */
  51   virtual void destroy() {
  52     // If guardCount_ is not 0, just set destroyPending_ to delay
  53     // actual destruction.
  54     if (getDestructorGuardCount() != 0) {
  55       destroyPending_ = true;
  56     } else {
  57       onDelayedDestroy(false);
  58     }
  59   }
  60
  61   /**
  62    * Helper class to allow DelayedDestruction classes to be used with
  63    * std::shared_ptr.
  64    *
  65    * This class can be specified as the destructor argument when creating the
  66    * shared_ptr, and it will destroy the guarded class properly when all
  67    * shared_ptr references are released.
  68    */
  69   class Destructor {
  70    public:
  71     void operator()(DelayedDestruction* dd) const {
  72       dd->destroy();
  73     }
  74   };
  75
  76   bool getDestroyPending() const {
  77     return destroyPending_;
  78   }
  79
  80  protected:
  81   /**
  82    * Protected destructor.
  83    *
  84    * Making this protected ensures that users cannot delete DelayedDestruction
  85    * objects directly, and that everyone must use destroy() instead.
  86    * Subclasses of DelayedDestruction must also define their destructors as
  87    * protected or private in order for this to work.
  88    *
  89    * This also means that DelayedDestruction objects cannot be created
  90    * directly on the stack; they must always be dynamically allocated on the
  91    * heap.
  92    *
  93    * In order to use a DelayedDestruction object with a shared_ptr, create the
  94    * shared_ptr using a DelayedDestruction::Destructor as the second argument
  95    * to the shared_ptr constructor.
  96    */
  97   ~DelayedDestruction() override = default;
  98
  99   DelayedDestruction()
 100     : destroyPending_(false) {
 101   }
 102
 103  private:
 104   /**
 105    * destroyPending_ is set to true if destoy() is called while guardCount_ is
 106    * non-zero. It is set to false before the object is deleted.
 107    *
 108    * If destroyPending_ is true, the object will be destroyed the next time
 109    * guardCount_ drops to 0.
 110    */
 111   bool destroyPending_;
 112
 113   void onDelayedDestroy(bool delayed) override {
 114     // check if it is ok to destroy now
 115     if (delayed && !destroyPending_) {
 116       return;
 117     }
 118     destroyPending_ = false;
 119     delete this;
 120   }
 121 };
 122 } // folly