Having this document as a reference will be great!
History
Many objects in WebKit are reference counted. The pattern used is
that classes have member functionsref and deref that increment and
decrement the reference count. Each call to ref has to be matched by
a call to deref. When the reference count hits 0, the object is
deleted. Many of these classes create new objects with a reference
count of 0; this is referred to as the floating state. An object in
floating state must have ref and then deref called on it before it
will be deleted. Many classes in WebCore implement this by
inheriting from the Shared class template.
"This" was ambiguous to me. I would say, "implement ref and deref"
instead of "implement this."
The inspiration for a solution came from the C++ standard class
template auto_ptr. These objects implement a model where assignment
is transfer of ownership. When you assign from one auto_ptr to
another, the donor becomes 0.
PassRefPtr is like RefPtr with a difference. When you copy a
PassRefPtr or assign the value of aPassRefPtr to a RefPtr or another
PassRefPtr, the original pointer value is set to 0; the operation is
done without any change to the reference count. Let’s take a look at
a new version of our example:
In the first paragraph, you use the term "donor." In the second
paragraph, you use the term "original pointer value." I think "source"
or "source pointer" would be good terms. Either way, you should pick
something to use consistently.
I think it would be helpful to explain why the source pointer must
become 0 -- i.e., "...the source pointer becomes 0, to prevent you
from using an object whose lifetime you no longer control."
// example, not preferred style PassRefPtr<Node> createSpecialNode()
{ PassRefPtr<Node> a = new Node; a->setSpecial(true); return a; }
RefPtr<Node> b = createSpecialNode();
The node object starts with a reference count of 0. When it’s
assigned to a, the reference count is incremented to 1. Then a gets
set to 0 when the return value PassRefPtr is created. Then the
return value is set to 0 when b is created.
It might be helpful to explain why all of this local variable churn is
OK, whereas reference count churn causes performance problems.
// some type casts RefPtr<DerivedNode> d =
static_pointer_cast<DerivedNode>(a);
Since static_pointer_cast is a made up name, it's not like the other
operators listed. You might want to annotate this line with a comment
like, "type casts use a special function."
Most of the time, we'll end up referring new programmers to this
document -- perhaps during a code review, or as an answer to a
question on IRC. Given that audience, I think it might be best to
begin the document with the "Guidelines" section, along with a pithy
example of each use, and then end with the history and the "why."
Understanding "why" is harder than just learning "how" and copying it.
Geoff
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo/webkit-dev
