Establishing Timing Dependencies

[Context: HL Kit … Basic Concepts and Terminology … Debugging Mechanisms]

Overview

Timing issues are a major nuisance when you are developing your data files. They are often hard to spot when you first introduce them, which means that you can't always assume that the problem arose with the last few changes that you made. Timing issues typically entail a tedious diagnostic process that takes the fun out of creating new data files. Most importantly, though, timing issues can quickly degenerate into a game of "Whack-A-Mole".

All of the different tasks within your data files are like a big chain of dominoes. They all need to be evaluated in the correct sequence to ensure that you reach the final goal of having an accurate character. However, if you move one domino, then that has ripple effects on the dominoes that were before and after it. Consequently, if you change the timing of one task to resolve a timing issue, you could find yourself simply creating a different timing issue between other tasks that have inter-dependencies with the task you moved. Squish one timing bug and up pops another.

Managing a large number of tasks and keeping all the timing dependencies clearly understood and enforced can quickly become a nightmare for an aspiring data file author. So the Kit provides a convenient mechanism that allows you to instantly detect when a timing issue has been introduced. We call the mechanism "timing dependencies" and it allows you to setup dependencies between different tasks that the compiler will verify for you automatically. This mechanism is the focus of the topics below.

Naming Tasks

In order to establish a timing dependency on another task, you need to assign that task a name. By default, each task is assigned a name by the Kit, but it's not something you'll be able to establish a dependency upon. So any task that will be referenced within a dependency must be given a name. This is achieved by assigning the "name" attribute within the XML element that defines the task.

Task names can be just about anything you want. The goal is to identify what the task is doing clearly and succinctly, but you're the judge of how best to accomplish that. For example, you could name a task something detailed like "Calculate the Final Value for Attributes" or something brief like "Attr Final". The only criteria to keep in mind when choosing a name is that you'll need to type it anywhere that has a dependency.

Establishing "before" and "after" Dependencies

Named tasks become anchor points within the overall evaluation cycle for your data files. Other tasks will reference these anchors by establishing timing dependencies with them. This is accomplished by identifying the named task and specifying the nature of the dependency.

A dependency can be either a "before" or an "after" relationship. A "before" relationship tells the compiler that this task must always be performed before the named task. An "after" relationship indicates that the task must always be performed after the named task. Since all tasks are evaluated in a sequence, there is never a possibility that two tasks can be performed at the same time. Even if you assign them the identical phase and priority, the HL engine will assign an order to them. Consequently, each timing dependency must specify either a before or after relationship.

You can assign any number of timing dependencies to a given task. So you could define an assortment of dependencies that require a task to occur after certain tasks and an assortment that require that task to occur before others.

NOTE! Tasks do not need to be named in order to specify dependencies. Only tasks that serve as anchor points and are referenced by other tasks require names. Consequently, if you have a named task, you could have five different tasks depend on that task, and none of the dependent tasks require names.

Using the Timing Report

When your data files are compiled, a timing report is generated. You can view this timing report at any time by going to the "Debug" menu and selecting the "View Timing Report" option. For most users, your web browser will be launched and the file will be viewed within it. The timing report is an XML file that contains information about all of the timing dependencies you've defined and the tasks involved. Details on the contents will be found within the Kit Reference section of the documentation.

The most important sections in the timing report are the first three, so we'll discuss them here briefly. The first section identifies the names of any tasks that are unknown. These are names that are referenced by a timing dependency and that have not been defined. For example, if you specify that a task has a "before" dependency on the task named "My Task" and you have not assigned that name to any task, the name will be listed as unknown and no dependency will be established.

The second section identifies any names that have been duplicated and are not valid. It is perfectly legal to use the same name on multiple tasks.