The Joy of Flex

(One in a series of random, daily, useful Flex tips.)

It’s very important to understand what’s going on when you add an event listener, and particularly when to use a weak reference; using a weak reference when you needed a strong one results in your listener method mysteriously not getting called; using a strong one when you needed a weak one causes a memory leak. Here’s the whole story.

When you write some code that adds an event listener to an EventDispatcher, you typically write one of the following lines of code in some method of your class:

// use a strong reference
cancelButton.addEventListener(MouseEvent.CLICK, onClick);

// use a weak reference (the last parameter specifies it)
myTimer.addEventListener(TimerEvent.TIMER, onTimer, false, 0, true);

In the first example, you’re saying to the cancel button instance: any time the user presses you and causes you to dispatch a CLICK event, I would like you to call my onClick method. This is a very common thing to do: for example, the Buzzword codebase has over 600 calls to addEventListener. When you call addEventListener() with a strong reference, you are implicitly telling the button to add a reference to the instance of your class that is making the call. Adding this reference ensures that the instance will still be around when the event is dispatched.

In the second example, you’re saying to the timer: each timer interval when you dispatch a TIMER event, please call my onTimer method. When you call adddEventListener() with a weak reference, you are explicitly telling the timer not to add a reference to the instance of your class that is making the call.

Here are some rules to remember:

You must use a strong reference when the listener function is an anonymous function closure; if you don’t, then there will be no reference to the anonymous function object, and it will go out of scope and get garbage collected.

It is usually safe to use a strong reference when the instance dispatching the event (i.e., the button in this example) is a member variable, because its lifetime and the listener’s lifetime are usually the same. That is, the listener already has a reference to the dispatcher, so whether you add another is irrelevant. But there’s an important exception…

You must use a weak reference when you are listening to TIMER events from a Timer that is designed to be running throughout the duration of its existence (i.e., is not designed to be stopped). This is true whether or not you have your own reference to the timer! Why? Because the framework will keep a reference to the timer as long as it is running, so if you ask the timer to add a strong reference to your listener’s instance, your listener’s instance will never go out of scope and will become a memory leak in your application.

I’m not sure this is a complete list of rules. Please post your suggestions or corrections in the comments.

Technorati Tags: Flex, Flex Tip of the Day