[webkit-dev] for review: RefPtr document

[Geoffrey Garen]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/webkit-dev/attachments/20071009/ec1cdbc6/attachment.html