Site hosted by Angelfire.com: Build your free website today!

Avoiding Javascript Race Conditions

Introduction

By now you must be quite used to seeing "object not found" errors when you load a web page. Any web page.
The most common cause of javascript errors is a load race condition, where there are references, in the HTML document, to a javascript function (or another object) that might not have loaded yet.
This article outlines why those errors occur, and outlines a couple of techniques you can use to ensure that they don't happen in your web pages, ever.

Why the race happens

When you load an HTML document (particularly over a slow connection), each block of in-line javascript (between <SCRIPT> and </SCRIPT> blocks) is parsed and executed as it is read. Any Javascript further ahead in the file is not necessarily available.
This means that any javascript that you have associated with HTML elements (for example, onclick event handlers), should never refer to any javascript routines defined only later in your page. Indeed, they should never assume that any object or variable defined later in the page... is defined.
When applying this rule you should not assume that referring to a file that defines a thing defines it straight away. Many javascript programmers assume, for example, that if they have a reference to an external javascript file in the <HEAD> section of their document, it can be expected to load before the <BODY> section of the document is parsed. This is not so. A browser opens separate connections to look up the documents specified in the SRC attributes of <SCRIPT> tags, and there's no guarantee that the javascript files will be loaded before any references to the functions or objects they define (particularly the first time a page is loaded).

Why onload events don't work

Some programmers write the code that refers to functions or objects that might not have loaded in routines that are called via the onload event of a BODY tag. This is NOT a good approach. Here's why it doesn't work, and what can go wrong (here by primary page I mean the page the user has requested, and not the other pages that the browser loads because they are referenced from it):

The BODY onload event fires too soon. It fires when the text of the primary page has loaded into memory, not when it has been parsed (that is, interpreted by the browser) in its entirety.
Anything loading via references from the primary page might not have finished yet.
Worse, functions or objects defined near the end of the page may not have been fully parsed yet. The Netscape parser seems slower, and over a fast connection, you will sometimes see the onload event failing because it refers to a function which, although it has been loaded, the browser hasn't looked at yet. So it says there's no such function, even though there is.
If you use an onload event, and put the function definition in the <HEAD> part of the document, you can at least expect that the browser will "find" your onload function. But you cannot be sure that anything it refers to will actually have been parsed.

It's also possible, in IE, to write code that relies on document state changes to tell it when the page has fully loaded. But not only isn't it portable once you do that, it isn't reliable either. It can tell you that a page and all the things it depends on are fully loaded, and be wrong. Particularly for framesets, where it tells you only if your document's children are loaded (mostly...). Not if your document's children's children are loaded.

Why putting your javascript code last still might not work

If you put javascript code at the very end of your document (just before the </BODY> tag that marks the end of the document), it won't execute until the rest of the page has been loaded into memory.
However, any external references (to, say, stylesheets, or via <SCRIPT> tags to javascript includes) may not yet have been resolved. So if you assume they have been your code will occasionally fail.
Still, if you've got code you want executed when the page has loaded into memory, this is the way to do it. Its big advantage over using onload is that it will work a little better. You mightn't be able to find functions if they're in external javascript files, but at least you can be reasonably sure that your on-load code will get executed (so long as there weren't any javascript errors earlier in the page!), which is more than you can say if you use the onload attribute.
There is a way to ensure that you wait until any javascript includes invoked by <SCRIPT> tags have all loaded...

The solution

I said earlier that any javascript that you have associated with HTML elements (for example, onclick event handlers), should never rely on calls to any javascript routines defined only later in your page, and that they should never assume that any object or variable defined later in the page... is defined, or that anything defined in a <SCRIPT> include has been so.
At first glance this sounds like a severe restriction. But hidden inside the restriction is the way around it. It is always possible to check if something is defined. You compare it to null.
By checking whether things are defined before you do things to them you can ensure that errors don't arise. But just "giving up" if the thing you want to refer to hasn't become defined yet isn't necessarily what you want to do either.
This is where the setTimeout() function can come to your rescue.
In, for example, the article on Quicksort, on this site, this technique is used to guarantee that the charting function, littleChart, is available, before it is called. If it isn't available, the in-line function uses setTimeOut to call itself again later (I chose after one second, you could pick any time interval you like). Its code looks like this:
```
<SCRIPT Language="JavaScript">
function drawCharts()
{
  if (document.isChartJSLoaded==null) 
  {
    //alert("charts not loaded");
    setTimeout("drawCharts()",1000);
    return;
  }
  //
  //... do things that rely on the functions defined by performanceChart.js
  //    here...  only at the point where we KNOW it has loaded
  //
}
</SCRIPT;>
```
At the top of the same document (but it could be anywhere, and even if you put it at the top of the document the javascript include mightn't finish until after the rest of the document has been read!), there is the usual javascript call-in. That doesn't change:
```
<SCRIPT Language="JavaScript" SRC="../../library/performanceChart.js">
</SCRIPT;>
```
I won't quote the source code of performanceChart.js - it merely renders the little graphs in the Quicksort article. The only line that is relevant is the very last one:
```
document.isChartJSLoaded = true;
```
So, to guarantee that you don't try to do anything that needs something that mightn't be defined, you can define something else only later and then exploit the fact that it won't be defined if the thing you need isn't. If you simply have to do that "anything", as soon as possible, you can whip up a setTimeOut "loop" (but not a busy polling loop, which will hang your browser!) that waits until the "something else" has become defined.

In other words, you use the race problem itself to solve the race problem.

Life's like that. Often the problem is its own solution. Instead of fighting against it, you can make it fight on your side. But it can be difficult to think of that, when you're struggling to meet a deadline!