Technobabble

“Why are you doing this?”

One of the hardest questions for me to answer is, “Why are you doing
this?” It’s also an excellent question, one that checks what I am
working on. I recently found myself asking this question when trying to use
something I’ve never tried to use before: weak references to DOM elements.

What are weak references?

For those of you coming from JavaScript-land, you know that once you hold
a DOM element as a property, it will last as long as the object you attached
that property to. (Depending on the usage, longer.) This is because XPConnect
generates a “strong” reference to the element, which through the magic of
XPCOM reference counting, requires the element not be deleted until all
strong references are gone – including yours. Weak references are different.
They are objects which hold a pointer to your real target, but they don’t
require the real target “stay alive”. In JavaScript pseudo-code, it looks a
little like this:

function getWeakReference(obj) {
var weakPtr = {
_realPtr: obj,
QueryReferent: function(aIID)
{
if (this._realPtr)
return this._realPtr.QueryInterface(aIID);
return null;
},
QueryInterface: function(aIID)
{
if (aIID.equals(Components.interfaces.nsIWeakReference) ||
aIID.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
}
};
return weakPtr;
}

There’s one thing this code can’t show you: Some time in the future,
weakPtr._realPtr could be destroyed, and set to null. That
doesn’t happen in normal code (thank heaven!). But with weak references, it
can happen at any time.

Why are you doing this?

There’s a long list of sub-projects and sub-sub-projects, etc., each of
which seems to require I look at something I hadn’t tried yet. Here’s the
current list, and how I started thinking (wrongly) I needed weak
references.

(Continued on the next page…)

  1. Existing XML and HTML editors do a fraction of “what I want to do”, and
    they’re not easy to extend to meet my vision. So I’m building my own
    extensible editor, Verbosio. That way, others can extend it any way they
    want. This is the classic “Scratch an itch” answer,
    especially since I think it would be really, really useful to others.
  2. One of these “What I want to do” items is is to take a template and
    build XML markup from it – say, a XUL grid from a grid template. So I
    need to write a language to define templates.
  3. Crafting a new language isn’t enough – you need a
    specification, an implementation, and test
    cases    . These three verify that the markup templates
    language works, and the test cases become real examples of how to use the
    language. (Note: This paragraph deserves its own blog entry – you really
    do need a spec, implementation and test cases!)
  4. One key test of the template language is the ability to build a
    template. No templates in this language exist (it’s a brand new
    language), so no one (including me) can know how to write one without
    some help. Therefore, I need to write a tool to guide template
    construction     in a separate XUL wizard window.
  5. In building templates, the user can copy, paste and edit in place the
    same basic code. (For example, you could have a template for ordered
    lists     like this one, and each item would be a copy of basic list
    item     elements.) It would be a key part of this template to mark
    fragments of code as “repeatable”, and provide controls for
    copying and pasting     these fragments.
  6. A template author also wants to define minimum and maximum
    numbers of copies     for the repeatable fragments, so my template
    construction wizard should support that.
  7. Updating a repeatable fragment’s minimum copy count requires
    its own specification, implementation and test cases    . I
    struggled with this for months, until I thought of XUL’s
    broadcast/observer model.
  8. The broadcast/observer model is good, but the implementation isn’t
    flexible enough. I need to get and set both JavaScript properties
    and XML attributes    . So I decided to re-implement the model with
    XML attributes.
  9. Observing attributes, setting properties and setting attributes are all
    trivial. However, observing properties directly on DOM elements isn’t.
    They don’t support Object.prototype.watch, which means I need to find
    some other way to detect changes. The simplest I can think of is
    timer-based observations of properties of the DOM
    elements, comparing previous values to current ones.
  10. This requires the timed observers ask the element for properties, but
    we don’t want the observers to keep the element around after the element
    would otherwise die. A strong reference keeps the element from dying.
    Therefore, timed observers should hold weak references to the
    element    .
  11. I tried using Components.utils.getWeakReference(), but that quickly led
    to a crash. At Boris Zbarsky’s suggestion, I then tried the element’s
    GetWeakReference() method, which returns a nsIWeakReference
    object. Unfortunately, I didn’t see many examples of
    nsIWeakReference in use, so I figured I needed to
    write a testcase for nsIWeakReference objects from
    elements    .
  12. In writing the XPCShell testcase, I found that DOM elements from the
    test weren’t being deleted (resulting in a nsIWeakReference
    object without a real element pointer). Forcing JavaScript garbage
    collection didn’t fix that, as this was a XPCOM cycle collector task.
    There’s also (currently) no obvious way to force XPCOM cycle collection
    from XPCShell, so I realized I needed to add XPCOM cycle
    collection to Components.utils    .
  13. At which point I realized I couldn’t visualize the chain from “write a
    language to define templates” to “writing a testcase for
    nsIWeakReference”. It was just too much for me to see the connections. I
    asked myself, Why am I doing all this?

Hence why I started writing this blog article, to analyze my own planning
and determine if I really needed to do all the steps. In writing this, I
realized that I’d made an error in my logic. Everything from item 4 onward
takes place in a separate DOM window, in a wizard. That means the template,
the template editing code, the repeated XML fragments, the broadcast/observer
code, all of it, would not live very long. After the user finished
their work with the template, all these pieces of code would be inaccessible
to the user and to other components, and XPCOM cycle collection would
presumably clean them up.

Individually, each step in the list leads logically to the next one. Taken
as a complete picture, step 10 makes an incorrect statement, and nothing
after it matters. Timed observers do NOT need to hold weak references to the
element, since neither the element nor the observer will be around for the
rest of the application’s life.

However, items 11 and 12 would still be useful – perhaps not to me, but to
others. I still think they need doing, but considering the size of this
“requirements stack trace” — and the dozens of other things I have to get
working for Verbosio 0.1 “Proof of concept”, I’m not going to spend any
immediate time on them.

Conclusion

Why am I sharing all this? It’s a classic forest-for-the-trees problem. If
you find yourself writing code for this grand project, and doing something so
far from it you can’t see how you got there… maybe you need to step back
and write it all down. In this case, it helped me realize I was off-track.
However, if everything checked out, I would have gladly continued to work on
weak references, knowing I was still progressing towards my ultimate goal.
(Certainly, items 1 through 9 are still valid statements, and I should
continue working on “timer-based observations of properties”.) Writing out
this “requirements stack trace” can help you see if you went astray, and if
you did, tell you where to get back on track. If you didn’t go astray, it
gives you confidence that you’re doing the right thing.

Ideally, it shouldn’t take you very long to write it all out – say, 15
minutes for a fast typist on a computer. If it does take longer to write out
all the steps, you really do have a stack overflow to worry about, and you
should think about ways you can cut back to #1. Whether you find the path is
correct from start to finish, or has a flaw in it, answering the question,
“Why am I doing this?” is always useful.