mirror of
https://github.com/Bubberstation/Bubberstation.git
synced 2025-12-31 12:01:47 +00:00
ae5a4f955d
## About The Pull Request Signals were initially only usable with component listeners, which while no longer the case has lead to outdated documentation, names, and a similar location in code. This pr pulls the two apart. Partially because mso thinks we should, but also because they really aren't directly linked anymore, and having them in this midstate just confuses people. [Renames comp_lookup to listen_lookup, since that's what it does](102b79694f) [Moves signal procs over to their own file](33d07d01fd) [Renames the PREQDELETING and QDELETING comsigs to drop the parent bit since they can hook to more then just comps now](335ea4ad08) [Does something similar to the attackby comsigs (PARENT -> ATOM)](210e57051d) [And finally passes over the examine signals](65917658fb) ## Why It's Good For The Game Code makes more sense, things are better teased apart, s just good imo ## Changelog 🆑 refactor: Pulled apart the last vestiges of names/docs directly linking signals to components /🆑
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_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)
|