mirror of
https://github.com/Bubberstation/Bubberstation.git
synced 2025-12-11 10:11:09 +00:00
6bb24ac773
When I changed the syntax of SS13.lua to account for the ability to properly index tables with datums, it turns out that the callbacks created for signal handlers and timeouts had circular references, resulting in hard-deletes. My first solution was to make it so signal handler and timeout callbacks use weakrefs, which get resolved in lua_state/call_function, but it turns out that, when calling the signal cleanup function, a qdeleted-but-not-yet-garbage-collected datum's weakref resolves to null because datum.gc_collected is set to GC_CURRENTLY_BEING_QDELETED before COMSIG_PARENT_QDELETING gets sent. To resolve this issue, Potato and Oranges both recommended that I make a snowflake variant of resolve which ignores whether the datum a weakref points to is qdeleted - only that it is null or it's weakref isn't the very weakref resolve was called on. This proc was given a lengthy autodoc comment describing when it should or shouldn't be used, to ensure it is only used in cases similar to the one I needed to create it for (needing to resolve a weakref to a datum in a COMSIG_PARENT_QDELETING handler registered on that very datum).
109 lines
4.3 KiB
Plaintext
109 lines
4.3 KiB
Plaintext
/// Creates a weakref to the given input.
|
|
/// See /datum/weakref's documentation for more information.
|
|
/proc/WEAKREF(datum/input)
|
|
if(istype(input) && !QDELETED(input))
|
|
if(isweakref(input))
|
|
return input
|
|
|
|
if(!input.weak_reference)
|
|
input.weak_reference = new /datum/weakref(input)
|
|
return input.weak_reference
|
|
|
|
/datum/proc/create_weakref() //Forced creation for admin proccalls
|
|
return WEAKREF(src)
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
/datum/weakref
|
|
var/reference
|
|
|
|
/datum/weakref/New(datum/thing)
|
|
reference = REF(thing)
|
|
|
|
/datum/weakref/Destroy(force)
|
|
var/datum/target = resolve()
|
|
qdel(target)
|
|
|
|
if(!force)
|
|
return QDEL_HINT_LETMELIVE //Let BYOND autoGC thiswhen nothing is using it anymore.
|
|
target?.weak_reference = null
|
|
return ..()
|
|
|
|
/**
|
|
* Retrieves the datum that this weakref is referencing.
|
|
*
|
|
* This will return `null` if the datum was deleted. This MUST be respected.
|
|
*/
|
|
/datum/weakref/proc/resolve()
|
|
var/datum/D = locate(reference)
|
|
return (!QDELETED(D) && D.weak_reference == src) ? D : null
|
|
|
|
/**
|
|
* 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_PARENT_QDELETING signal handler registered on that very same datum,
|
|
* just use resolve instead.
|
|
*/
|
|
/datum/weakref/proc/hard_resolve()
|
|
var/datum/D = locate(reference)
|
|
return (D?.weak_reference == src) ? D : null
|
|
|
|
/datum/weakref/vv_get_dropdown()
|
|
. = ..()
|
|
VV_DROPDOWN_OPTION(VV_HK_WEAKREF_RESOLVE, "Go to reference")
|
|
|
|
/datum/weakref/vv_do_topic(list/href_list)
|
|
. = ..()
|
|
if(href_list[VV_HK_WEAKREF_RESOLVE])
|
|
if(!check_rights(NONE))
|
|
return
|
|
var/datum/R = resolve()
|
|
if(R)
|
|
usr.client.debug_variables(R)
|