/datum/weakref
A weakref holds a non-owning reference to a datum.
The datum can be referenced again using resolve().
To figure out why this is important, you must understand how deletion in BYOND works.
Imagine a datum as a TV in a living room. When one person enters to watch TV, they turn it on. Others can come into the room and watch the TV. When the last person leaves the room, they turn off the TV because it's no longer being used.
A datum being deleted tells everyone who's watching the TV to stop. If everyone leaves properly (AKA cleaning up their references), then the last person will turn off the TV, and everything is well. However, if someone is resistant (holds a hard reference after deletion), then someone has to walk in, drag them away, and turn off the TV forecefully. This process is very slow, and it's known as hard deletion.
This is where weak references come in. Weak references don't count as someone watching the TV. Thus, when what it's referencing is destroyed, it will hopefully clean up properly, and limit hard deletions.
A common use case for weak references is holding onto what created itself.
For example, if a machine wanted to know what its last user was, it might
create a var/mob/living/last_user. However, this is a strong reference to
the mob, and thus will force a hard deletion when that mob is deleted.
It is often better in this case to instead create a weakref to the user,
meaning this type definition becomes var/datum/weakref/last_user.
A good rule of thumb is that you should hold strong references to things
that you own. For example, a dog holding a chew toy would be the owner
of that chew toy, and thus a var/obj/item/chew_toy reference is fine
(as long as it is cleaned up properly).
However, a chew toy does not own its dog, so a var/mob/living/dog/owner
might be inferior to a weakref.
This is also a good rule of thumb to avoid circular references, such as the
chew toy example. A circular reference that doesn't clean itself up properly
will always hard delete.
Procs | |
| hard_resolve | SERIOUSLY READ THE AUTODOC COMMENT FOR THIS PROC BEFORE EVEN THINKING ABOUT USING IT |
|---|---|
| resolve | Retrieves the datum that this weakref is referencing. |
Proc Details
hard_resolve
SERIOUSLY READ THE AUTODOC COMMENT FOR THIS PROC BEFORE EVEN THINKING ABOUT USING IT
Like resolve, but doesn't care if the datum is being qdeleted but hasn't been deleted yet.
The return value of this proc leaves hanging references if the datum is being qdeleted but hasn't been deleted yet.
Do not do anything that would create a lasting reference to the return value, such as giving it a tag, putting it on the map, adding it to an atom's contents or vis_contents, giving it a key (if it's a mob), attaching it to an atom (if it's an image), or assigning it to a datum or list referenced somewhere other than a temporary value.
Unless you're resolving a weakref to a datum in a COMSIG_QDELETING signal handler registered on that very same datum, just use resolve instead.
resolve
Retrieves the datum that this weakref is referencing.
This will return null if the datum was deleted. This MUST be respected.