Change return types of refcount methods.

AddRef() now returns void, and Release() returns an enum
RefCountReleaseStatus, to indicate whether or not this Release
call implied deletion.

Bug: webrtc:8270
Change-Id: If2fb77f26118b61751b51c856af187c72112c630
Reviewed-on: https://webrtc-review.googlesource.com/3320
Commit-Queue: Niels Moller <nisse@webrtc.org>
Reviewed-by: Karl Wiberg <kwiberg@webrtc.org>
Reviewed-by: Taylor Brandstetter <deadbeef@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#20366}

rtc_base/refcount.h

diff --git a/rtc_base/refcount.h b/rtc_base/refcount.h
index f29d279..fb0971c 100644
--- a/rtc_base/refcount.h
+++ b/rtc_base/refcount.h
@@ -12,12 +12,52 @@
 
 namespace rtc {
 
-// Reference count interface.
+// 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 int AddRef() const = 0;
-  virtual int Release() const = 0;
+  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() {}
 };