Changes between Version 3 and Version 4 of GRefPtr

Timestamp:

Jan 20, 2014, 5:49:41 AM (12 years ago)

Author:

Adrian Perez de Castro

Comment:

Reword some parts, add when-to-use section

GRefPtr

@@ -9 +9 @@
  * [source:trunk/Source/WTF/wtf/gobject/GRefPtr.h Source/WTF/wtf/gobject/GRefPtr.h]
  * [source:trunk/Source/WTF/wtf/gobject/GRefPtr.cpp Source/WTF/wtf/gobject/GRefPtr.h]
-
 
 == Usage ==
@@ -70 +69 @@
 == Floating references ==
 
-Instances of most types have a ''floating reference'' when created. Most `GObject`-derived types, but also some other types have floating references (`GVariant` is one of those). It is incorrect to use `adoptGRef()` on newly created instances of types which use floating references: the floating reference has to be converted on a full reference. Assigning to a `GRefPtr` will convert the floating reference to a full reference.
+Some types have a ''floating reference'' when created, for example `GtkWidget` and derived types and `GVariant`. Most of the time it is incorrect to use `adoptGRef()` on newly created instances of types which use floating references: the floating reference has to be converted on a full reference. Assigning to a `GRefPtr` will convert the floating reference to a full reference.
 
 Incorrect usage:
@@ -83 +82 @@
 GRefPtr<GVariant> variant = g_variant_new("s", "Floating reference is sank");
 }}}
+
+== When to use ==
+
+In the following cases it is recommended to use `GRefPtr<T>`:
+
+ * When holding references as attribute members of instances. Note that this also makes it easier to write accessor methods at the API level, as the refing/unrefing of objects is done automatically:
+{{{
+#!cpp
+struct FooPrivate {
+     GRefPtr<GVariant> someData;
+};
+
+// Public API method
+void foo_set_data(Foo* foo, GVariant* data) {
+     FooPrivate* priv = foo_get_private(foo);
+     // Takes care of unrefing the previously held object
+     // and also refing the passed object.
+     priv->someData = data;
+}
+}}}
+
+ * When using local references to objects which should be freed/unrefed when the local variable goes out of scope:
+{{{
+#!cpp
+void doSomethingWithALocalReference() {
+    GRefPtr<GVariant> temporaryData = g_variant_new("s", "SpamAndEggs");
+    // Use “temporaryData” as needed, it will be freed automatically
+    // when the variable goes out of scope at the end of the function
+}
+}}}
+
+In the following cases it is ''not'' recommended to use `GRefPtr<T>`:
+
+ * When creating an initially unowned object —that is, it has a floating reference— which is going to be passed to another function/object that will consume the floating reference. For example:
+{{{
+#!cpp
+GVariant* createData(int value) {
+    // This function does not use the new value; the caller
+    // is responsible of consuming the floating reference.
+    return g_variant_new("(si)", "int", value);
+}
+
+void someOtherCode() {
+    // Picks the GVariant created by the above function and
+    // grabs the floating reference, to make sure intData is
+    // freed when it goes out of scope.
+    GRefPtr<GVariant> intData = createData(42);
+    useIntData(intData);
+}
+}}}