Document Acedia's event system

3 years ago · e4794554ad
2 changed files with 393 additions and 1 deletions
--- a/docs/events.md
+++ b/docs/events.md
@ -0,0 +1,392 @@
 # Signals and slots system
 Acedia provides its own unique event system that is more powerful than regular
 `delegate`s and easier to use than listener-type objects like `GameRules`.
 It's best demonstrated with an example from AcediaFixes' feature
 that deals with friendly fire-related exploits.
 Said feature has to catch and handle `NetDamage()` event from `GameRules` and,
 with Acedia's signal/slot system, handler can be added with a single line:
 ```unrealscript
 _.unreal.gameRules.OnNetDamage(self).connect = NetDamageHandler;
 ```
 `OnNetDamage()` is a *signal function* responsible for adding new handlers
 for the `NetDamage` event.
 Function `NetDamageHandler` has to have an appropriate signature
 (parameters and return value types) for the event and will be called each time
 `NetDamage` event occurs, starting from the next occurrence.
 Unlike raw `delegate`s, that can each only store one function, signal/slot
 system allows us to have however many handlers we need:
 ```unrealscript
 //  All of those will be called on `NetDamage` event
 _.unreal.gameRules.OnNetDamage(self).connect = NetDamageNext;
 _.unreal.gameRules.OnNetDamage(self).connect = NetDamageTry;
 _.unreal.gameRules.OnNetDamage(self).connect = NetDamageRevolution;
 _.unreal.gameRules.OnNetDamage(self).connect = NetDamageEvolutionR;
 ```
 `self` argument is necessary for the cleanup and refers to the object that is
 responsible for the added handler - if it gets deallocated, then all of
 the associated handlers will be automatically removed:
 ```unrealscript
 //  This assumes that `someObj` is a child class of `AcediaObject`
 _.unreal.gameRules.OnNetDamage(someObj).connect = NetDamageHandler;
 _.memory.Free(someObj); // After this line `NetDamageHandler()` won't be used
 ```
 Most of the time this parameter is going to be `self`, since normally each
 object adds its own functions as event handlers.
 Once you no longer need to handle an event, you can *disconnect* from it:
 ```unrealscript
 _.unreal.gameRules.OnNetDamage(self).Disconnect();
 //  To disconnect some object `someObj`:
 _.unreal.gameRules.OnNetDamage(someObj).Disconnect();
 ```
 This will remove all handlers associated with the object passed as
 an argument.
 > **NOTE:**
 > Even though handlers associated with deallocated object will be automatically
 > removed, it is still good practice to manually remove all handlers associated
 > with it inside a finalizer, since otherwise "dead" handlers will be stored
 > until related event is triggered.
 Removing individual handlers is also possible, but can be a bit cumbersome and
 is not recommended.
 > **NOTE:**
 > Our signals and slots take this moniker after [Qt](https://doc.qt.io)'s
 > events system;
 > however, what they are and how they work is different and shouldn't
 > be mixed up.
 ## [Advanced] How signals and slots work
 ### Delegates overview
 This system was created because of limitations of `delegate`s in UnrealEngine 2.
 One can declare `delegate` inside any class:
 ```unrealscript
 class MyClass extends Object;
 delegate MyDelegate()
 {
    //  This code will be executed if no function is assigned to the delegate.
    Log("Empty message");
 }
 ```
 then assign a function to them and any time a delegate is called - an assigned
 function will be called instead:
 ```unrealscript
 function handler()
 {
    Log("Handler is called!");
 }
 local MyClass obj;
 obj = new class'MyClass';
 obj.MyDelegate();       // "Empty message" is logged
 obj.MyDelegate = handler;
 obj.MyDelegate();       // "Handler is called!" is logged
 obj.MyDelegate = none;  // Reset delegate to its default state
 obj.MyDelegate();       // "Empty message" is logged
 ```
 However they have their limitations, main one being that you can neither assign
 several functions to a `delegate` nor can you create an array of `delegate`s to
 have several handlers for your events.
 ### `Slot`s are boxed `delegate`s, `Signal`s are arrays of `Slot`s
 Acedia bypasses this limitation by essentially boxing `delegate`s.
 If you are unfamiliar with the concept of boxing, it is discussed
 [here](./objects.md).
 `Slot` is just an object that contains a single `delegate` (usually called
 `connect()`) with some extra code to support cleanup of no longer needed
 `Slot`s.
 Wrapping `delegate`s into `Slot`s allows us to store them in arrays represented
 by `Signal`s: each `Signal` is usually associated with some sort of an event and
 can refer (be connected to) several `Slot`s, therefore supporting several
 different handlers for its event.
 `Signal`s are usually declared as internal variables and are different from
 *signal function* like `_.unreal.gameRules.OnNetDamage()`.
 Connecting a handler to an event with line like
 `OnNetDamage(self).connect = NetDamage`
 actually results in performing following steps:
 1. Appropriate `Signal` object is found / accessed;
 2. New `Slot` object for that `Singal` is created and returned;
 3. `connect` delegate for returned `Slot` gets assigned with a handler function
    (`NetDamage` in above example).
 ```unrealscript
 //  [GameRulesAPI.uc]
 public final function GameRules_OnNetDamage_Slot OnNetDamage(
    AcediaObject receiver)
 {
    local Signal        signal;
    local UnrealService service;
    //  These two lines are implementation detail for `OnNetDamage()`,
    //  you can store your `signal` object wherever you need.
    service = UnrealService(class'UnrealService'.static.Require());
    signal = service.GetSignal(class'GameRules_OnNetDamage_Signal');
    //  This is the important line that creates new slot
    return GameRules_OnNetDamage_Slot(signal.NewSlot(receiver));
 }
 //  [FixFFHack.uc]
 //  `connect` is simply a delegate defined inside
 //  `GameRules_OnNetDamage_Slot` object
 _.unreal.gameRules.OnNetDamage(self).connect = NetDamage;
 ```
 If returned signal is not assigned any function, then it will be automatically
 cleaned up at some later point.
 We cannot directly check whether a `delegate` was assigned some value, but
 `connect`'s default implementation calls special protected method `DummyCall()`
 that tells us that its slot is empty.
 ### Disconnecting
 So how does `_.unreal.gameRules.OnNetDamage(someObj).Disconnect()` work?
 Same as above, `_.unreal.gameRules.OnNetDamage(someObj)` creates a new empty
 slot associated with `someObj`.
 This slot is aware of both `signal` its connected to and associated `someObj`.
 `Disconnect()` method makes our `slot` inform its `signal` that all `slot`s
 related to `someObj` (including itself) must be disconnected and deallocated.
 This means that disconnecting object's `slot`s from the `signal` with
 `Disconnect()`always involves creation of the new `slot` that will never be
 connected to any handler method.
 It is a roundabout way of doing things, but it provides a simple interface for
 the task that shouldn't be performed often enough to affect performance.
 ## [Advanced] How to make your own `signal`s and `slot`s
 Providing support for your own signals and slots actually takes quite a bit more
 work that using them.
 Here we will consider main use cases.
 ### Simple notification events
 If you need to add an event with handlers that don't take any parameters and
 don't return anything, then easiest way it to use `SimpleSignal` / `SingleSlot`
 classes:
 ```unrealscript
 class MyEventClass extends AcediaObject;
 var private SimpleSignal onMyEventSignal;
 protected function Constructor()
 {
    onMyEventSignal = SimpleSignal(_.memory.Allocate(class'SimpleSignal'));
 }
 protected function Finalizer()
 {
    _.memory.Free(onMyEventSignal);
    onMyEventSignal = none;
 }
 public function SimpleSlot OnMyEvent(AcediaObject receiver)
 {
    return SimpleSlot(onMyEventSignal.NewSlot(receiver));
 }
 //  Suppose you want to emit the signal when this function is called...
 public function SimpleSlot FireOffMyEvent(AcediaObject receiver)
 {
    //  ...simply call this and all the slots will have their handlers called
    onMyEventSignal.Emit();
 }
 ```
 Then you can use `OnMyEvent()` as a *signal function*:
 ```unrealscript
 //  To add handlers
 myEventClassInstance.OnMyEvent(self).connect = handler;
 //  To remove handlers
 myEventClassInstance.OnMyEvent(self).Disconnect();
 ```
 ### Events with parameters
 Some of the events, like `OnNetDamage()` in our first examples, can take
 parameters.
 We cannot use `SimpleSignal` or `SimpleSlot` for them and have to define new
 classes that will wrap around `delegate` with an appropriate signature.
 You simply need to follow the template and define new classes like this:
 ```unrealscript
 class MySignal extends Signal;
 public final function Emit(<PARAMETERS>)
 {
    local Slot nextSlot;
    StartIterating();
    nextSlot = GetNextSlot();
    while (nextSlot != none)
    {
        MySlot(nextSlot).connect(<PARAMETERS>);
        nextSlot = GetNextSlot();
    }
    CleanEmptySlots();
 }
 defaultproperties
 {
    relatedSlotClass = class'MySlot'
 }
 ```
 ```unrealscript
 class MySlot extends Slot;
 delegate connect(<PARAMETERS>)
 {
    DummyCall(); // This allows Acedia to cleanup slots without set handlers
 }
 protected function Constructor()
 {
    connect = none;
 }
 protected function Finalizer()
 {
    super.Finalizer();
    connect = none;
 }
 defaultproperties
 {
 }
 ```
 where you can use any set of parameters instead of `<PARAMETERS>`.
 You can check out `Unreal_OnTick_Signal` and `Unreal_OnTick_Slot` as
 an example.
 ### Events with return values
 Sometimes you want your handlers to respond in some way to the event.
 You can either allow them to modify input parameters (e.g. by declaring them as
 `out`) or allow them to have return value.
 `OnNetDamage()`, for example, is allowed to modify incoming damage by returning
 a new value.
 To add signals / slots that handle return value use following templates:
 ```unrealscript
 class MySignal extends Signal;
 public final function <RETURN_TYPE> Emit(<PARAMETERS>)
 {
    local <RETURN_TYPE> newValue;
    local Slot          nextSlot;
    StartIterating();
    nextSlot = GetNextSlot();
    while (nextSlot != none)
    {
        newValue = <SLOT_CLASS>(nextSlot).connect(<PARAMETERS>);
        //  This check if necessary before using returned value
        if (!nextSlot.IsEmpty())
        {
            //  Now handle `newValue` however you see fit
        }
        nextSlot = GetNextSlot();
    }
    CleanEmptySlots();
    //  Return whatever you see fit after handling all the slots
    return <END_RETURN_VALUE>;
 }
 defaultproperties
 {
    relatedSlotClass = class'MySlot'
 }
 ```
 ```unrealscript
 class MySlot extends Slot;
 delegate <RETURN_TYPE> connect(<PARAMETERS>)
 {
    DummyCall();
    //  Return anything you want:
    //  this value will be filtered inside corresponding `Signal`
    //  if no handler is set to the associated slot
    return <???>;
 }
 protected function Constructor()
 {
    connect = none;
 }
 protected function Finalizer()
 {
    super.Finalizer();
    connect = none;
 }
 ```
 For working example you can check out `GameRules_OnNetDamage_Signal` and
 `GameRules_OnNetDamage_Slot` classes.
 ## [Advanced] How to remove particular `slot`
 In our very first example we've seen that we can remove all `slot`s for
 `OnNetDamage()`, associated with `someObj` by calling
 `_.unreal.gameRules.OnNetDamage(someObj).Disconnect()`.
 But sometimes it might be necessary to remove only one slot.
 In that case you'll have to store that slot in a separate variable:
 ```unrealscript
 //  Each `signal` can have its own `slot` type
 var GameRules_OnNetDamage_Slot trackedSlot;
 var int trackedSlotLifeVersion;
 // ...
 // Record new `slot` in a variable, then set `connect` delegate
 trackedSlot = _.unreal.gameRules.OnNetDamage(self);
 trackedSlot.connect = handler;
 trackedSlotLifeVersion = trackedSlot.GetLifeVersion();
 // ...
 // 1. You can then change `slot`'s handler
 if (trackedSlotLifeVersion == trackedSlot.GetLifeVersion()) {
    trackedSlot.connect = handler2;
 }
 // ...
 // 2. Or deallocate `slot` once it's no longer needed -
 // its handler won't be called again
 trackedSlot.FreeSelf(trackedSlotLifeVersion);
 trackedSlot = none;
 ```
 Here we record *life version* because it is `signal` and not us that is
 responsible for the deallocation of `slot`s.
 If we don't check life versions, we might use `slot` reallocated for a different
 purpose.
 This shouldn't happen unless you deallocate `trackedSlot` in some other way
 (e.g. with `_.unreal.gameRules.OnNetDamage(self).Disconnect()`), but its safer
 to do this check.
 Not accessing separate `slot`s is even safer.
 > **NOTE:**
 > `singal`s themselves also track `slot`'s life versions and will be able to
 > tell if you've deallocated them.
--- a/docs/index.md
+++ b/docs/index.md
@ -51,4 +51,4 @@ about any topic of interest, but we strongly recommend that you first read up on
 the fundamental topics:
 [what is API](./api.md),
 at least non-advanced topics of [Acedia's objects / actors](./objects.md)
-and about signal / slot system.
+and about [signal / slot system](./events.md).