Guide to signals - Revision history

Itsmeowdev: Add patterns and clarify send_signal

2023-12-28T06:18:34Z

Add patterns and clarify send_signal

← Older revision		Revision as of 06:18, 28 December 2023
Line 76:		Line 76:
	</pre>		</pre>

	The first argument is the emitter, so often it is <code>src</code>, however this is not a rule. You can also emit signals to other objects! The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.		The first argument is the emitter, so often it is <code>src</code>, however this is not a rule. You can also emit signals '''from''' other objects! It is a common pattern to emit a signal '''from'' another object, and have the object listen to signals on itself to respond to it. The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

	Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.		Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.
Line 89:		Line 89:

	If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.		If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.

			=== Signal Patterns ===

			There are many ways to utilize signals, here are some common ones:

			* '''Event->Listener:''' Use a global signal to emit an 'event' occurring to anything that is listening.
			* '''Component<->Parent:''' Use a signal to communicate data between a component and its parent. This avoids the bad practice of GetComponent(), and allows components to react to events from the parent. This can use combinations of other patterns, but with components rather than objects.
			* '''Object->Object:''' Use a signal to inform an object of something happening to it. The listening object will register a signal to itself, if it cares about this interaction.
			* '''QDELETING:''' <code>COMSIG_PARENT_QDELETING</code> is one of the most used signals, it fires when the emitter is Destroy()ing. This allows the listener to clean up any references it has to the emitter, so it can delete properly.
			* '''Object->Listener:''' Use a signal to inform listeners of something happening within an object. This is used to avoid hard-coding unnecessary references. An example of this is the MOB_LOGOUT or MOB_DEATH signal.
			* '''Self->Listener:''' Use a signal to react to an event from within an object inside that same object. This is used when the two events are not related, to avoid hard-coding the event response. It can also be used to react to events from within the parent type without performing a method override.


	== Global Signals ==		== Global Signals ==

Itsmeowdev: Describe global signals

2023-12-28T05:57:04Z

Describe global signals

@@ Line 89: / Line 89: @@
 If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.
 {{Contribution guides}}
 [[Category:Guides]] [[Category:Game Resources]]

Itsmeowdev: /* Emitting or sending a signal */ Include emits to other objects

2023-12-28T05:49:21Z

Emitting or sending a signal: Include emits to other objects

← Older revision		Revision as of 05:49, 28 December 2023
Line 76:		Line 76:
	</pre>		</pre>

	The first argument is the emitter, so ~~generally~~ it is <code>src</code>, however this is not a rule. The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.		The first argument is the emitter, so often it is <code>src</code>, however this is not a rule. You can also emit signals to other objects! The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

	Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.		Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.

Itsmeowdev: Add categories

2023-12-19T06:33:51Z

Add categories

← Older revision		Revision as of 06:33, 19 December 2023
Line 89:		Line 89:

	If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.		If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.

			{{Contribution guides}}
			[[Category:Guides]] [[Category:Game Resources]]

Itsmeowdev: Created page with "== What is a signal? == A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen". == Why signals? == In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on..."

2023-12-19T06:33:05Z

Created page with "== What is a signal? == A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen". == Why signals? == In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on..."

New page

== What is a signal? ==

A signal is a standard interface for calling procs on components and other objects. It prevents holding hard references and allows the procs to be called on multiple objects from one "event". It is an event-subscriber system, where one thing "shouts", or emits an event, and multiple things "listen".

== Why signals? ==

In code, signals can improve quality and stability, because you do not have to collect a list of things and then call a proc on them if you want to inform them of a certain event happening. For example, previously, you may have needed to hold a reference to something or maintain a list of things that want to hear about an event occuring. Signals are built into every datum and object, and perform this duty automatically. Signals can also replace the need to check values on a component or other object, as you can simply emit a signal requesting it, and have the other object listen for it and respond.

For example, many things in the game care if a player dies. Because of that, we have a signal called <code>COMSIG_MOB_DEATH</code>, that is emitted by mobs when they die. It provides data with it as well (what emitted it, current health, etc.) that may be useful to the "listener". Signals can also be returned with a value to the emitter, allowing further interactions between objects.

== How do I use signals? ==

Signals are made of several parts.

'''An emitter''', which calls <code>SEND_SIGNAL()</code>. This emits the signal to anything that is currently listening to the emitter.

'''A listener''', which calls <code>RegisterSignal</code> with the emitter as an argument, and provides a signal type and a signal callback.

'''A signal type''', which is the type of signal being emitted or listened to. This is what <code>COMSIG_MOB_DEATH</code> is - it's a unique string that denotes the type of signal being sent, and when it is sent or how it is to be used.

'''A signal callback''', which is a proc that receives data from the emitter's signal for a specific signal type.

=== Adding or selecting a type ===

All signals have a type, which is the unique string describing what the signal is used for or when it is emitted. All types are stored in <code>code/__DEFINES/dcs/signals/</code>, and sorted into categories based on the type of the emitter. For example, any signal sent only by <code>/mob/</code> types should be in <code>signals_mob/signals_mob.dm</code>.

This is what a signal type definition looks like. The string in the signal should be unique to the signal type - and is usually the lowercase of everything after <code>COMSIG_</code>. It is also standard to document when a signal is sent within the comment, either by stating it or providing a proc path for the case where <code>SEND_SIGNAL</code> is used.

<pre>
#define COMSIG_MOB_DEATH "mob_death" //! from base of mob/death(): (gibbed)
</pre>

The parent path for the signal should be the highest path for which the signal is relevant. For example, there is both <code>COMSIG_MOB_DEATH</code> and <code>COMSIG_LIVING_DEATH</code>, because some places only care when a living mob dies. When creating a signal, determine which context is most useful or applicable, and apply it to the highest object possible. <code>COMSIG_LIVING_DEATH</code> provides additional arguments (or context) when the signal is emitted, making it necessary should anything require this information.

=== Listening for a signal ===

This is one of the most common patterns in the entire codebase, so it is absolutely vital to understand. When you want to receive a signal from an atom or datum, you call <code>RegisterSignal</code> with that atom or datum as the first argument, a signal type, and then a signal listener.

This is often done during <code>Initialize()</code>, however it can take place at any time so long as the emitter exists. Do note that RegisterSignal is a type on /datum, so it is implicitly calling <code>src.RegisterSignal()</code>. This means you can technically force another datum to register a signal listener via <code>other_thing.RegisterSignal(emitter)</code>, however this is not recommended.

<pre>
RegisterSignal(emitter_here, COMSIG_MOB_DEATH, PROC_REF(on_mob_death))
</pre>

As you can see, the signal registration requires a signal listener. These are procs with a special format. In a signal's comment, or when it is emitted, there is usually a list of arguments, or simply no arguments. These arguments are provided to the signal listener as additional data. When defining a listener, you can choose to include these arguments if you need them.

<pre>
/datum/example/proc/on_mob_death(mob/parent, gibbed)
SIGNAL_HANDLER
</pre>

As you can see, the first argument provided to a signal listener is ALWAYS the emitter, so you can assume for <code>COMSIG_MOB_DEATH</code> that it is of the type <code>/mob</code>. The remaining arguments are defined by the emitter itself when the signal is sent. You do not need to include any arguments if you do not want them.

You can also see that signal listeners always start with <code>SIGNAL_HANDLER</code>. This is a special DEFINE that disables sleeping within the proc, as sleeping in a signal listener can break the master controller's timing. It is important to include this in all signal listeners, since it is not checked automatically otherwise.

=== Stopping listening to a signal ===

Registering a signal on an emitter stores a reference to that emitter. This is problematic if the emitter were to be deleted or dissociated from the listener, as there is not a reference the other way around. It is generally the responsibility of the listener to control its own references to the emitter. For example, if we have an object that was listening for another object's death, but only once, we could unregister the signal during <code>on_mob_death</code> so as to prevent holding a reference.

Unregistering a signal is simple:

<pre>
UnregisterSignal(emitter_here, COMSIG_MOB_DEATH)
</pre>

This will remove <code>src</code>'s listener for <code>COMSIG_MOB_DEATH</code>.

It is also important to know that all atoms and datums will automatically unregister all their signals when they are destroyed, so there is no need to do so yourself during <code>Destroy()</code>, however some things like components or species need to remove signals when they are 'dissociated', such as on_species_loss, or when a component is detached, as they are not always immediately destroyed.

=== Emitting or sending a signal ===

To send a signal, and retrieve results from listeners, you simply use the <code>SEND_SIGNAL</code> define.

<pre>
SEND_SIGNAL(src, COMSIG_MOB_DEATH)
</pre>

The first argument is the emitter, so generally it is <code>src</code>, however this is not a rule. The second argument is always the type. You may provide additional arguments that will be sent as extra arguments to all listeners, as discussed earlier.

Another key feature of <code>SEND_SIGNAL</code> is that it can return a result. If a signal listener has a return value, it will be given as the result of <code>SEND_SIGNAL</code>. This means you can retrieve and act on data from listeners.

For example, this is used by emag signals:

<pre>
/atom/proc/use_emag(mob/user, obj/item/card/emag/hacker)
if(!SEND_SIGNAL(src, COMSIG_ATOM_SHOULD_EMAG, user))
SEND_SIGNAL(src, COMSIG_ATOM_ON_EMAG, user, hacker)
</pre>

If the result of <code>COMSIG_ATOM_SHOULD_EMAG</code> is <code>FALSE</code>, then <code>COMSIG_ATOM_ON_EMAG</code> is sent as well. Do note that this is intentionally inverted in case of an error, since procs will return null when they error, so this should be taken into consideration when sending signals to unknown listeners.