Handle ( object )
Parameters
| object - a custom Type object, or Null |
Description
|
Turns a Type object into a plain integer that identifies it. Type objects are the things you make with New - a monster, a bullet, a save slot. They are wonderful inside your program and useless outside it: you cannot write one into a file, stuff it into a bank, or send one over the network. Handle solves that by giving each object a small integer of its own, and Object turns the integer back into the object later. The number is stable: ask for the same object's handle a hundred times and you get the same answer every time. Numbers start at 1 and only ever count upwards, so a fresh object never reuses a retired number. Handle of Null is always 0, which makes 0 a natural "nobody" value for an empty slot in a bank or a network packet. Typical uses are a save file that records which monster a quest was pointing at, a network message that says "the object with id 7 just died", and a bank of enemy ids that a particle effect can consult without holding a real reference. It is also the cheapest way to print something identifying about an object while debugging. Two gotchas. Handles are only meaningful inside the run that made them - they are not stable from one launch of your game to the next, so a save file that stores raw handles must rebuild its own mapping on load rather than trusting the numbers. And once you Delete the object, its handle no longer resolves: Object answers Null for it. That is actually useful, because it turns a stale id into a safe, detectable miss instead of a crash. Handle is a compiler special form rather than an ordinary function, so it is written straight in front of the object - Handle m and Handle(m) both work. It cannot be used inside a Worker Function; jobs run on their own thread and are not allowed to touch the object tables. See also: Object, New, Delete, Each, Type. |
Example
; Handle Example ; -------------- ; A tiny monster roster - the sort of list a game keeps for its enemies Type Monster Field name$ Field hp End Type For i=1 To 3 m.Monster=New Monster m\name="Goblin "+i m\hp=i*10 Next ; Handle turns a Type object into a plain integer. That number can go ; into a save file, a bank or a network message - places a Type object ; itself cannot travel. Print "Roster:" For m.Monster=Each Monster Print " "+m\name+" hp "+m\hp+" handle "+Handle(m) Next Print "" ; Asking for the same object twice always gives the same number boss.Monster=Last Monster Print "Same object asked twice : "+Handle(boss)+" then "+Handle(boss) ; A Null object always handles to 0, so 0 is a safe "nobody" value nobody.Monster=Null Print "Handle of a Null object : "+Handle(nobody) Print "" ; Object turns the number back into the object again saved=Handle(boss) back.Monster=Object.Monster(saved) Print "Object.Monster("+saved+") is "+back\name ; After the object is deleted the same number resolves to Null, which ; is a cheap way to spot a reference that has gone stale Delete boss gone.Monster=Object.Monster(saved) If gone=Null Then Print "After Delete, handle "+saved+" gives Null" Print "" Print "Press any key to close the example" WaitKey End
Index