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 247005 229b03af6f2b7d8f598d768531cffcbd0c508552
parent 247004 b95c3dd6b73e345c0746c9ab3cc411426277e075
child 247006 eee2aca9e032dacadab51e0f2337e9f256883004
push id28848
push userryanvm@gmail.com
push dateWed, 03 Jun 2015 20:00:13 +0000
treeherdermozilla-central@0920f2325a6d [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersfroydnj
bugs1169337
milestone41.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
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") \