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.