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 <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     VLOG(4) << "DelayedDestruction::destroy()";
  55     if (getDestructorGuardCount() != 0) {
  56       destroyPending_ = true;
  57     } else {
  58       onDestroy_(false);
  59     }
  60   }
  61
  62   /**
  63    * Helper class to allow DelayedDestruction classes to be used with
  64    * std::shared_ptr.
  65    *
  66    * This class can be specified as the destructor argument when creating the
  67    * shared_ptr, and it will destroy the guarded class properly when all
  68    * shared_ptr references are released.
  69    */
  70   class Destructor {
  71    public:
  72     void operator()(DelayedDestruction* dd) const {
  73       dd->destroy();
  74     }
  75   };
  76
  77   bool getDestroyPending() const {
  78     return destroyPending_;
  79   }
  80
  81  protected:
  82   /**
  83    * Protected destructor.
  84    *
  85    * Making this protected ensures that users cannot delete DelayedDestruction
  86    * objects directly, and that everyone must use destroy() instead.
  87    * Subclasses of DelayedDestruction must also define their destructors as
  88    * protected or private in order for this to work.
  89    *
  90    * This also means that DelayedDestruction objects cannot be created
  91    * directly on the stack; they must always be dynamically allocated on the
  92    * heap.
  93    *
  94    * In order to use a DelayedDestruction object with a shared_ptr, create the
  95    * shared_ptr using a DelayedDestruction::Destructor as the second argument
  96    * to the shared_ptr constructor.
  97    */
  98   virtual ~DelayedDestruction() = default;
  99
 100   DelayedDestruction()
 101     : destroyPending_(false) {
 102
 103     onDestroy_ = [this] (bool delayed) {
 104       // check if it is ok to destroy now
 105       if (delayed && !destroyPending_) {
 106         return;
 107       }
 108       VLOG(4) << "DelayedDestruction::onDestroy_ delayed=" << delayed;
 109       delete this;
 110       (void)delayed; // prevent unused variable warnings
 111     };
 112   }
 113
 114  private:
 115   /**
 116    * destroyPending_ is set to true if destoy() is called while guardCount_ is
 117    * non-zero.
 118    *
 119    * If destroyPending_ is true, the object will be destroyed the next time
 120    * guardCount_ drops to 0.
 121    */
 122   bool destroyPending_;
 123 };
 124 } // folly