Debug Handle Checks

Debug handle checks

The originals, and a BlitzLLVM program compiled without -d, carry on when a command is given the handle of something that was never made, was freed already or is 0 (the result of a load that failed): most commands do nothing or give 0, and some stop the program. A bug like that usually shows far from where it was made. A debug build (blitzcc -d) stops at the command that got the handle, with the line of the command and a message like

Runtime Error: TextureWidth: the texture 3 does not exist (never made or already freed).
Runtime Error: PlaySound: the sound is 0, which is no sound (was it made, or did it fail to load?).

What a debug build checks, on top of what every build already refuses (banks, files and streams, brushes, entities, surfaces, fonts, gadgets, timers, samplers and images that do not exist stop the program everywhere):

Handle	Commands	Release build
Texture	FreeTexture of a freed texture or 0, TextureWidth, TextureHeight, EntityTexture and BrushTexture with a texture that does not exist	ignored, 0 and ignored
Image	FreeImage of an image that is freed already or 0	ignored
Sound	every sound command with the 0 of a sound that failed to load	ignored
Channel	every channel command with a channel that was never given out	ignored
Movie	every movie command with the 0 of a movie that failed to open or a movie that was closed	ignored, 0

The 0 that a failed load gives counts as a handle that does not exist, so FreeTexture, FreeImage, FreeSound, CloseMovie, FreeFont, FreeTimer, FreeGadget and FreeTreeViewNode of 0 stop a debug build as well (freeing, closing and deleting must be given something that exists); FreeEntity, FreeBrush, FreeBank, CloseFile, Delete and the like already stop every build. What stays legal: EntityTexture and BrushTexture with the texture 0 (which takes the texture off), and a channel that is over, as channels end by themselves. Object.Type(handle) gives Null for a handle that names no object in every build, as the language says.

A debug build also ignores AsyncLoading, AsyncSaving and the environment variables BLITZLLVM_ASYNC_LOAD and BLITZLLVM_ASYNC_SAVE. A file that can not be loaded or decoded then stops the program at the command that loaded it, and a save that fails tells so in the result of the command that asked for it. The commands themselves keep working: TextureReady, ImageReady and EntityReady always give 1, and SavesPending always gives 0.

Runtime errors as breakpoints

After the message of a runtime error is written, a debug build breaks into the debugger that is attached to it (DebugBreak on Windows, SIGTRAP where a debugger is tracing the program on Linux), so the call stack and the variables of the error can be looked at. When the debugger lets the program go on, it ends as it does without one. Without a debugger nothing is raised and the program ends with its message as usual, and a build without -d never breaks.