The client complained that the progress bar stalls the first time you run the app in the browser. Refreshing the page causes the application to start immediately, as if everything has been loaded. I reproduced the bug with bandwidth throttling. That made me think: “the assets are being fully loaded, but the progress bar doesn’t seem to care”.

With further investigation, I realized that I solved the same problem over a year ago. When one creates Loaders on the fly, such as in a loop, one often does not keep any reference to these Loaders outside of the scope of the function. Since it is a good habit to make event listeners weak, it is possible for the garbage collector to flag these Loaders for removal before they even have a chance to fire their complete event.

So to make sure that the progress bar does not stall, I needed to keep a reference to the Loader that I create within my loop. I simply pushed every Loader to an array. Once everything finished loading and the application started, I cleared the array to allow the garbage collector to take care of the rest.

Problem

Progress bar stalls while preloading images.

Cause

Loaders with weak event listeners and no references to them within the application.

Solution

Use an array to store references to the Loaders until all of them have finished loading.

The application domain and definition loading is one of the things that is not documented in a way the common mortal can understand. By popular demand, I will attempt to explain it the way I understand it. I will provide some examples along the way. Before I continue, here is a link to the official documentation on ApplicationDomain.

I will explain class definitions and domains, and then tell you what you can do to properly unload your movies and assets.

Class Definitions

Everything that you load has to be stored somewhere. It’s easy to understand the visual elements because you can just stick them on the stage. But what about class definitions?

For all of you who aren’t sure what class definitions are, remember all the classes that you import on top of the document when writing AS3. You can then instantiate your mx.controls.Button or flash.events.Event in the document. You can then add instances of visual components to the display list (stage).

Now think about your SWF for a minute. When you create a symbol in the library and export it for ActionScript, you’re basically creating a definition in the SWF. That definition will be loaded into some domain and you can instantiate it on the stage.

If you look at the schema, you’ll see all the class definitions in the current domain. When you close the application, all instances will be destroyed, class definitions removed and memory freed. If you decide to load an external SWF, you can choose where to load the definitions: in the same box as Class1 or in its own box.

ApplicationDomain.currentDomain

If you choose to load them in the same box as Class1, what will happen when you decide to unload your SWF? Any instances on that stage are destroyed, any definitions in its box are removed and memory is freed. Oh wait, there were no definitions in its box, so there’s nothing to remove from it. The file is unloaded in any case, but the definitions live on as a parasite in the box of our application. That’s right, a parasite. You can’t target a specific definition to unload. If you want to unload ClassC, you’ll need to unload the whole app (basically just close it). That’s not what you want to do. You want your app to run all day.

What is the solution? Remember there are 2 choices when loading your SWF. What if you want your loaded SWF to keep it’s garbage to itself? Sure.

New ApplicationDomain

So instead of loading you SWF into the application’s domain, load it into its own domain. How?

var appDomain:ApplicationDomain = new ApplicationDomain();
var context:LoaderContext = new LoaderContext(false, appDomain);
var loader:Loader = new Loader();
loader.load(new URLRequest("myButtons.swf"), context);

We created a new domain and loaded all definitions into it. So now our application has 2 domains: the default one and a new one. You can create as many new domains as you have SWFs to load.

What will happen now if you unload your SWF? All classes are no longer in the same box, and the Loader that loaded our SWF has a reference to our new domain.  That means that when you unload your SWF, the domain (box with definitions A, B and C) will be removed and memory freed. Yay!

Conclusion

So what does that all mean? Should we create a new domain for EVERY file that we load? Sure you can. But you shouldn’t. There are some nice functions such as getDefinitionByName() that I want to be able to use without searching for the domain in which my definition is contained. If I have a mini-game that requires 20 SWF files, searching for that little symbol in all these domains can be painful. I would rather create 1 new domain (say domainA) and load all 20 SWFs into it. Then I can access my symbol definition from domainA, and unload this domain when no longer needed. For a second mini-game, I’ll create domainB. The idea is not to stick everything into the application’s domain.

Please tell me if this post helped you with your memory usage. Also, feel free to add to my explanation if I missed something.

In order to allow your objects to be garbage-collected, you can either remove all listeners from it or use weak event listeners instead (don’t forget to remove other references to it as well). To make a listener weak, you must set the 5th parameter of the addEventListener method to true, like this:

var btn:Button = new Button();
btn.addEventListener(MouseEvent.CLICK, clickHandler, false, 0, true);

But you have to be very careful where you use weak event listeners. When you instantiate an object in a function’s scope and then add weak event listeners, your object could be garbage-collected before it had a chance to dispatch these events. Example:

private function getStuff():void {
    var service:HTTPService = new HTTPService();
    service.url = "get-stuff.php";
    service.addEventListener(ResultEvent.RESULT, resultHandler, false, 0, true);
}

In this case, you should either avoid using weak listeners and remove them manually, or add a reference to your object outside of the function’s scope to prevent it from being garbage-collected too early.

I tried loading SWFs using the Loader class and unloading them immediately after the load completes. These SWFs contained symbols that were exported for ActionScript (linkage). When providing a LoaderContext with its applicationDomain property set to ApplicationDomain.currentDomain, even if you unload the SWF, memory of that symbol definition is never released. However, if you do not provide one, when you unload the SWF, memory is released.

Conclusion: if you are to use linked library symbols in your projects, avoid loading it in the application’s domain for performance reasons. In one of my projects, I used it intensely and my application lagged and crashed after a few hours of use (could be much less depending on the size of the symbols that you have).