Bug 1169337 - Clarify MOZ_{NON_,}OWNING_REF/MOZ_UNSAFE_REF documentation. r=froydnj
authorMichael Layzell <michael@thelayzells.com>
Mon, 01 Jun 2015 14:44:00 -0400
changeset 269663 229b03af6f2b7d8f598d768531cffcbd0c508552
parent 269662 b95c3dd6b73e345c0746c9ab3cc411426277e075
child 269664 eee2aca9e032dacadab51e0f2337e9f256883004
push id2540
push userwcosta@mozilla.com
push dateWed, 03 Jun 2015 20:55:41 +0000
reviewersfroydnj
bugs1169337
milestone41.0a1
Bug 1169337 - Clarify MOZ_{NON_,}OWNING_REF/MOZ_UNSAFE_REF documentation. r=froydnj
mfbt/Attributes.h
--- a/mfbt/Attributes.h
+++ b/mfbt/Attributes.h
@@ -410,28 +410,47 @@
  *   value is allocated on the heap, and will as a result check such allocations
  *   during MOZ_STACK_CLASS and MOZ_NONHEAP_CLASS annotation checking.
  * MOZ_IMPLICIT: Applies to constructors. Implicit conversion constructors
  *   are disallowed by default unless they are marked as MOZ_IMPLICIT. This
  *   attribute must be used for constructors which intend to provide implicit
  *   conversions.
  * MOZ_NO_ARITHMETIC_EXPR_IN_ARGUMENT: Applies to functions. Makes it a compile
  *   time error to pass arithmetic expressions on variables to the function.
- * MOZ_OWNING_REF: Applies to declarations of pointer types.  This attribute
- *   tells the compiler that the raw pointer is a strong reference, and that
- *   property is somehow enforced by the code.  This can make the compiler
+ * MOZ_OWNING_REF: Applies to declarations of pointers to reference counted
+ *   types.  This attribute tells the compiler that the raw pointer is a strong
+ *   reference, where ownership through methods such as AddRef and Release is
+ *   managed manually.  This can make the compiler ignore these pointers when
+ *   validating the usage of pointers otherwise.
+ *
+ *   Example uses include owned pointers inside of unions, and pointers stored
+ *   in POD types where a using a smart pointer class would make the object
+ *   non-POD.
+ * MOZ_NON_OWNING_REF: Applies to declarations of pointers to reference counted
+ *   types.  This attribute tells the compiler that the raw pointer is a weak
+ *   reference, which is ensured to be valid by a guarantee that the reference
+ *   will be nulled before the pointer becomes invalid.  This can make the compiler
  *   ignore these pointers when validating the usage of pointers otherwise.
- * MOZ_NON_OWNING_REF: Applies to declarations of pointer types.  This attribute
- *   tells the compiler that the raw pointer is a weak reference, and that
- *   property is somehow enforced by the code.  This can make the compiler
- *   ignore these pointers when validating the usage of pointers otherwise.
- * MOZ_UNSAFE_REF: Applies to declarations of pointer types.  This attribute
- *   should be used for non-owning references that can be unsafe, and their
- *   safety needs to be validated through code inspection.  The string argument
- *   passed to this macro documents the safety conditions.
+ *
+ *   Examples include an mOwner pointer, which is nulled by the owning class's
+ *   destructor, and is null-checked before dereferencing.
+ * MOZ_UNSAFE_REF: Applies to declarations of pointers to reference counted types.
+ *   Occasionally there are non-owning references which are valid, but do not take
+ *   the form of a MOZ_NON_OWNING_REF.  Their safety may be dependent on the behaviour
+ *   of API consumers.  The string argument passed to this macro documents the safety
+ *   conditions.  This can make the compiler ignore these pointers when validating
+ *   the usage of pointers elsewhere.
+ *
+ *   Examples include an nsIAtom* member which is known at compile time to point to a
+ *   static atom which is valid throughout the lifetime of the program, or an API which
+ *   stores a pointer, but doesn't take ownership over it, instead requiring the API
+ *   consumer to correctly null the value before it becomes invalid.
+ *
+ *   Use of this annotation is discouraged when a strong reference or one of the above
+ *   two annotations can be used instead.
  * MOZ_NO_ADDREF_RELEASE_ON_RETURN: Applies to function declarations.  Makes it
  *   a compile time error to call AddRef or Release on the return value of a
  *   function.  This is intended to be used with operator->() of our smart
  *   pointer classes to ensure that the refcount of an object wrapped in a
  *   smart pointer is not manipulated directly.
  */
 #ifdef MOZ_CLANG_PLUGIN
 #  define MOZ_MUST_OVERRIDE __attribute__((annotate("moz_must_override")))
@@ -444,17 +463,17 @@
 #  else
 #    define MOZ_ONLY_USED_TO_AVOID_STATIC_CONSTRUCTORS __attribute__((annotate("moz_global_class"))) \
             MOZ_TRIVIAL_CTOR_DTOR
 #  endif
 #  define MOZ_IMPLICIT __attribute__((annotate("moz_implicit")))
 #  define MOZ_NO_ARITHMETIC_EXPR_IN_ARGUMENT __attribute__((annotate("moz_no_arith_expr_in_arg")))
 #  define MOZ_OWNING_REF __attribute__((annotate("moz_strong_ref")))
 #  define MOZ_NON_OWNING_REF __attribute__((annotate("moz_weak_ref")))
-#  define MOZ_UNSAFE_REF(reason) __attribute__((annotate("moz_strong_ref")))
+#  define MOZ_UNSAFE_REF(reason) __attribute__((annotate("moz_weak_ref")))
 #  define MOZ_NO_ADDREF_RELEASE_ON_RETURN __attribute__((annotate("moz_no_addref_release_on_return")))
 /*
  * It turns out that clang doesn't like void func() __attribute__ {} without a
  * warning, so use pragmas to disable the warning. This code won't work on GCC
  * anyways, so the warning is safe to ignore.
  */
 #  define MOZ_HEAP_ALLOCATOR \
     _Pragma("clang diagnostic push") \