From d6bac61b64c7f441940f306a00d37dd452327b1c Mon Sep 17 00:00:00 2001 From: Harald Alvestrand Date: Tue, 31 Oct 2023 11:42:45 +0000 Subject: [PATCH] Move RefCountInterface to api/ and webrtc: namespace This CL just moves the definition and adds a forward. Actually using the new definition is left for later CLs. Bug: webrtc:15622 Change-Id: I6d97ef45b98f9eb193c59dd7f8a89c99cfe0ba9a Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/325381 Reviewed-by: Tomas Gunnarsson Reviewed-by: Mirko Bonadei Commit-Queue: Harald Alvestrand Cr-Commit-Position: refs/heads/main@{#41048} --- api/BUILD.gn | 5 ++++ api/ref_count.h | 67 ++++++++++++++++++++++++++++++++++++++++++++ rtc_base/BUILD.gn | 1 + rtc_base/ref_count.h | 57 ++++++------------------------------- 4 files changed, 81 insertions(+), 49 deletions(-) create mode 100644 api/ref_count.h diff --git a/api/BUILD.gn b/api/BUILD.gn index 46703f93ce..1eb38760d0 100644 --- a/api/BUILD.gn +++ b/api/BUILD.gn @@ -438,6 +438,11 @@ rtc_source_set("wrapping_async_dns_resolver") { absl_deps = [ "//third_party/abseil-cpp/absl/memory" ] } +rtc_source_set("ref_count") { + visibility = [ "*" ] + sources = [ "ref_count.h" ] +} + rtc_source_set("scoped_refptr") { visibility = [ "*" ] sources = [ "scoped_refptr.h" ] diff --git a/api/ref_count.h b/api/ref_count.h new file mode 100644 index 0000000000..5209277038 --- /dev/null +++ b/api/ref_count.h @@ -0,0 +1,67 @@ +/* + * Copyright 2011 The WebRTC Project Authors. All rights reserved. + * + * Use of this source code is governed by a BSD-style license + * that can be found in the LICENSE file in the root of the source + * tree. An additional intellectual property rights grant can be found + * in the file PATENTS. All contributing project authors may + * be found in the AUTHORS file in the root of the source tree. + */ +#ifndef API_REF_COUNT_H_ +#define API_REF_COUNT_H_ + +namespace webrtc { + +// Refcounted objects should implement the following informal interface: +// +// void AddRef() const ; +// RefCountReleaseStatus Release() const; +// +// You may access members of a reference-counted object, including the AddRef() +// and Release() methods, only if you already own a reference to it, or if +// you're borrowing someone else's reference. (A newly created object is a +// special case: the reference count is zero on construction, and the code that +// creates the object should immediately call AddRef(), bringing the reference +// count from zero to one, e.g., by constructing an rtc::scoped_refptr). +// +// AddRef() creates a new reference to the object. +// +// Release() releases a reference to the object; the caller now has one less +// reference than before the call. Returns kDroppedLastRef if the number of +// references dropped to zero because of this (in which case the object destroys +// itself). Otherwise, returns kOtherRefsRemained, to signal that at the precise +// time the caller's reference was dropped, other references still remained (but +// if other threads own references, this may of course have changed by the time +// Release() returns). +// +// The caller of Release() must treat it in the same way as a delete operation: +// Regardless of the return value from Release(), the caller mustn't access the +// object. The object might still be alive, due to references held by other +// users of the object, but the object can go away at any time, e.g., as the +// result of another thread calling Release(). +// +// Calling AddRef() and Release() manually is discouraged. It's recommended to +// use rtc::scoped_refptr to manage all pointers to reference counted objects. +// Note that rtc::scoped_refptr depends on compile-time duck-typing; formally +// implementing the below RefCountInterface is not required. + +enum class RefCountReleaseStatus { kDroppedLastRef, kOtherRefsRemained }; + +// Interfaces where refcounting is part of the public api should +// inherit this abstract interface. The implementation of these +// methods is usually provided by the RefCountedObject template class, +// applied as a leaf in the inheritance tree. +class RefCountInterface { + public: + virtual void AddRef() const = 0; + virtual RefCountReleaseStatus Release() const = 0; + + // Non-public destructor, because Release() has exclusive responsibility for + // destroying the object. + protected: + virtual ~RefCountInterface() {} +}; + +} // namespace webrtc + +#endif // API_REF_COUNT_H_ diff --git a/rtc_base/BUILD.gn b/rtc_base/BUILD.gn index 6abae807fe..6fa8f0d392 100644 --- a/rtc_base/BUILD.gn +++ b/rtc_base/BUILD.gn @@ -369,6 +369,7 @@ rtc_source_set("refcount") { ] deps = [ ":macromagic", + "../api:ref_count", "../api:scoped_refptr", ] } diff --git a/rtc_base/ref_count.h b/rtc_base/ref_count.h index d8d652abd8..60a11fa5c7 100644 --- a/rtc_base/ref_count.h +++ b/rtc_base/ref_count.h @@ -10,57 +10,16 @@ #ifndef RTC_BASE_REF_COUNT_H_ #define RTC_BASE_REF_COUNT_H_ +// Transition file for backwards compatibility with source code +// that includes the non-API file. + +#include "api/ref_count.h" + namespace rtc { -// Refcounted objects should implement the following informal interface: -// -// void AddRef() const ; -// RefCountReleaseStatus Release() const; -// -// You may access members of a reference-counted object, including the AddRef() -// and Release() methods, only if you already own a reference to it, or if -// you're borrowing someone else's reference. (A newly created object is a -// special case: the reference count is zero on construction, and the code that -// creates the object should immediately call AddRef(), bringing the reference -// count from zero to one, e.g., by constructing an rtc::scoped_refptr). -// -// AddRef() creates a new reference to the object. -// -// Release() releases a reference to the object; the caller now has one less -// reference than before the call. Returns kDroppedLastRef if the number of -// references dropped to zero because of this (in which case the object destroys -// itself). Otherwise, returns kOtherRefsRemained, to signal that at the precise -// time the caller's reference was dropped, other references still remained (but -// if other threads own references, this may of course have changed by the time -// Release() returns). -// -// The caller of Release() must treat it in the same way as a delete operation: -// Regardless of the return value from Release(), the caller mustn't access the -// object. The object might still be alive, due to references held by other -// users of the object, but the object can go away at any time, e.g., as the -// result of another thread calling Release(). -// -// Calling AddRef() and Release() manually is discouraged. It's recommended to -// use rtc::scoped_refptr to manage all pointers to reference counted objects. -// Note that rtc::scoped_refptr depends on compile-time duck-typing; formally -// implementing the below RefCountInterface is not required. - -enum class RefCountReleaseStatus { kDroppedLastRef, kOtherRefsRemained }; - -// Interfaces where refcounting is part of the public api should -// inherit this abstract interface. The implementation of these -// methods is usually provided by the RefCountedObject template class, -// applied as a leaf in the inheritance tree. -class RefCountInterface { - public: - virtual void AddRef() const = 0; - virtual RefCountReleaseStatus Release() const = 0; - - // Non-public destructor, because Release() has exclusive responsibility for - // destroying the object. - protected: - virtual ~RefCountInterface() {} -}; +// TODO(bugs.webrtc.org/15622): Deprecate and remove these aliases. +using webrtc::RefCountInterface; +using webrtc::RefCountReleaseStatus; } // namespace rtc