folly/io/async/DelayedDestructionBase.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 <assert.h>
  20 #include <boost/noncopyable.hpp>
  21 #include <functional>
  22 #include <glog/logging.h>
  23 #include <inttypes.h>
  24
  25 namespace folly {
  26
  27 /**
  28  * DelayedDestructionBase is a helper class to ensure objects are not deleted
  29  * while they still have functions executing in a higher stack frame.
  30  *
  31  * This is useful for objects that invoke callback functions, to ensure that a
  32  * callback does not destroy the calling object.
  33  *
  34  * Classes needing this functionality should:
  35  * - derive from DelayedDestructionBase directly
  36  * - pass a callback to onDestroy_ which'll be called before the object is
  37  *   going to be destructed
  38  * - create a DestructorGuard object on the stack in each public method that
  39  *   may invoke a callback
  40  *
  41  * DelayedDestructionBase does not perform any locking.  It is intended to be
  42  * used only from a single thread.
  43  */
  44 class DelayedDestructionBase : private boost::noncopyable {
  45  public:
  46   virtual ~DelayedDestructionBase() = default;
  47
  48   /**
  49    * Classes should create a DestructorGuard object on the stack in any
  50    * function that may invoke callback functions.
  51    *
  52    * The DestructorGuard prevents the guarded class from being destroyed while
  53    * it exists.  Without this, the callback function could delete the guarded
  54    * object, causing problems when the callback function returns and the
  55    * guarded object's method resumes execution.
  56    */
  57   class DestructorGuard {
  58    public:
  59
  60     explicit DestructorGuard(DelayedDestructionBase* dd) : dd_(dd) {
  61       ++dd_->guardCount_;
  62       assert(dd_->guardCount_ > 0); // check for wrapping
  63     }
  64
  65     DestructorGuard(const DestructorGuard& dg) : dd_(dg.dd_) {
  66       ++dd_->guardCount_;
  67       assert(dd_->guardCount_ > 0); // check for wrapping
  68     }
  69
  70     ~DestructorGuard() {
  71       assert(dd_->guardCount_ > 0);
  72       --dd_->guardCount_;
  73       if (dd_->guardCount_ == 0) {
  74         dd_->onDestroy_(true);
  75       }
  76     }
  77
  78    private:
  79     DelayedDestructionBase* dd_;
  80   };
  81
  82  protected:
  83   DelayedDestructionBase()
  84     : guardCount_(0) {}
  85
  86   /**
  87    * Get the number of DestructorGuards currently protecting this object.
  88    *
  89    * This is primarily intended for debugging purposes, such as asserting
  90    * that an object has at least 1 guard.
  91    */
  92   uint32_t getDestructorGuardCount() const {
  93     return guardCount_;
  94   }
  95
  96   /**
  97    * Implement onDestroy_ in subclasses.
  98    * onDestroy_() is invoked when the object is potentially being destroyed.
  99    *
 100    * @param delayed  This parameter is true if destruction was delayed because
 101    *                 of a DestructorGuard object, or false if onDestroy_() is
 102    *                 being called directly from the destructor.
 103    */
 104   std::function<void(bool)> onDestroy_;
 105
 106  private:
 107   /**
 108    * guardCount_ is incremented by DestructorGuard, to indicate that one of
 109    * the DelayedDestructionBase object's methods is currently running.
 110    *
 111    * If the destructor is called while guardCount_ is non-zero, destruction
 112    * will be delayed until guardCount_ drops to 0.  This allows
 113    * DelayedDestructionBase objects to invoke callbacks without having to worry
 114    * about being deleted before the callback returns.
 115    */
 116   uint32_t guardCount_;
 117 };
 118 } // folly