Tutorial · Chapter 17 of 23

Choose when DLLs load and who owns them

Compare startup and first-call loading, then keep a shared rule available when another feature fails to load.

Jump to a section

Put the disk wait where the player can expect it

A game can load rules before showing its first screen, wait until the player asks for a feature, or load during an explicit transition such as entering a level. The policy controls when the disk read happens. Once the bytes are in REU, dispatch can still move them into the execution window as needed.

PolicyWhen it reads diskWhere to check availability
.preloadDuring generated startup, before main.At entry, before presenting the feature as ready.
.on_demandOn the first call that needs the unloaded export.At the optional call result.
.manualWhen the program explicitly loads or acquires it.At the load result, before calling.

The first successful activation can still cost a copy and relocation even after startup loaded the payload. When using an embedded current module, load() can seed the cache from the PRG. The examples here use disk files.

Build the same rule with three loading policies

The Rules program prints whether its registry row is loaded when main starts. The same three calls then exercise a byte, a Boolean, and a word result. Change the policy while keeping the disk payload name and call arguments the same.

Load before main

Current row
current {
    load = .preload;
    load_file = "rules";
}

Load on the first call

Current row
current {
    load = .on_demand;
    load_file = "rules";
}

Preload starts with ENTRY LOADED. On-demand and manual start with ENTRY EMPTY. The manual build inserts Rules.loadFromDisk("rules") after the entry check and reports failure if that operation fails. All three successful runs show BYTE 06 WORD 1335 and FALSE IS A RESULT. The Boolean value false belongs to a successful call. null means the call was unavailable.

Complete policy source

For a failure exercise, make a second on-demand disk with only the boot PRG. It starts with ENTRY EMPTY and the first call reports DLL UNAVAILABLE.

Give each feature its own reference

In the next exercise the score display acquires FixedMath. A separate terrain feature requires FixedMath too. Declare that dependency in the loader's requires list. A graph acquire visits prerequisites before the requested module and gives the terrain feature its own references. It makes the code available without calling any exports.

Declare the prerequisite

Loader rows
dependency terrain_rules {
    file = "terrain";
    requires = .{ .fixed_math };
}
dependency fixed_math {
    file = "fixedmath";
    requires = .{};
}

Use the feature

Terrain caller
fn showTerrain() void {
    if (Terrain.acquireGraph()) {
        if (Terrain.cost(3)) |cost| {
            c64.console.print("TERRAIN COST {x}\n", .{cost});
        }
        Terrain.releaseGraph();
    } else {
        c64.console.print("TERRAIN UNAVAILABLE\n", .{});
    }
}
StepFixedMath ownersWhat the caller can do
Score display acquires FixedMathScore displayCall the bonus rule.
Terrain acquires its graphScore display and terrain featureCall the terrain rule. Both payloads can stay in REU.
Terrain releases its graphScore displayKeep using the bonus rule.
Score display releases FixedMathNoneA manual binding call now returns null.

These graph edges describe availability. A module export still runs only when called, and a caller needs a binding and build-time sidecars for the exports it uses. The compiler rejects missing nodes and cycles.

Remove the terrain file and follow rollback

The complete disk prints TERRAIN COST 05, BONUS 07, and RULES RELEASED. On the second disk, keep FixedMath and omit Terrain. The terrain acquire fails after reaching its prerequisite. The loader rolls back the reference introduced by that acquire, so the original score display can still print BONUS 07. After the final release the binding is unavailable again.

Complete graph caller · Terrain producer · FixedMath producer

Expect TERRAIN UNAVAILABLE, BONUS 07, and RULES RELEASED on the second disk. Release a graph only after its acquire succeeds. For startup and first-call graph policies, see loading dependency graphs.