1 /* 2 * Copyright 2011 The WebRTC Project Authors. All rights reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 #ifndef RTC_BASE_REF_COUNT_H_ 11 #define RTC_BASE_REF_COUNT_H_ 12 13 namespace rtc { 14 15 // Refcounted objects should implement the following informal interface: 16 // 17 // void AddRef() const ; 18 // RefCountReleaseStatus Release() const; 19 // 20 // You may access members of a reference-counted object, including the AddRef() 21 // and Release() methods, only if you already own a reference to it, or if 22 // you're borrowing someone else's reference. (A newly created object is a 23 // special case: the reference count is zero on construction, and the code that 24 // creates the object should immediately call AddRef(), bringing the reference 25 // count from zero to one, e.g., by constructing an rtc::scoped_refptr). 26 // 27 // AddRef() creates a new reference to the object. 28 // 29 // Release() releases a reference to the object; the caller now has one less 30 // reference than before the call. Returns kDroppedLastRef if the number of 31 // references dropped to zero because of this (in which case the object destroys 32 // itself). Otherwise, returns kOtherRefsRemained, to signal that at the precise 33 // time the caller's reference was dropped, other references still remained (but 34 // if other threads own references, this may of course have changed by the time 35 // Release() returns). 36 // 37 // The caller of Release() must treat it in the same way as a delete operation: 38 // Regardless of the return value from Release(), the caller mustn't access the 39 // object. The object might still be alive, due to references held by other 40 // users of the object, but the object can go away at any time, e.g., as the 41 // result of another thread calling Release(). 42 // 43 // Calling AddRef() and Release() manually is discouraged. It's recommended to 44 // use rtc::scoped_refptr to manage all pointers to reference counted objects. 45 // Note that rtc::scoped_refptr depends on compile-time duck-typing; formally 46 // implementing the below RefCountInterface is not required. 47 48 enum class RefCountReleaseStatus { kDroppedLastRef, kOtherRefsRemained }; 49 50 // Interfaces where refcounting is part of the public api should 51 // inherit this abstract interface. The implementation of these 52 // methods is usually provided by the RefCountedObject template class, 53 // applied as a leaf in the inheritance tree. 54 class RefCountInterface { 55 public: 56 virtual void AddRef() const = 0; 57 virtual RefCountReleaseStatus Release() const = 0; 58 59 // Non-public destructor, because Release() has exclusive responsibility for 60 // destroying the object. 61 protected: ~RefCountInterface()62 virtual ~RefCountInterface() {} 63 }; 64 65 } // namespace rtc 66 67 #endif // RTC_BASE_REF_COUNT_H_ 68