include/event.h

   1 /*
   2  * InspIRCd -- Internet Relay Chat Daemon
   3  *
   4  *   Copyright (C) 2018-2019 Sadie Powell <sadie@witchery.services>
   5  *   Copyright (C) 2015, 2018 Attila Molnar <attilamolnar@hush.com>
   6  *
   7  * This file is part of InspIRCd.  InspIRCd is free software: you can
   8  * redistribute it and/or modify it under the terms of the GNU General Public
   9  * License as published by the Free Software Foundation, version 2.
  10  *
  11  * This program is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  13  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  14  * details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20
  21 #pragma once
  22
  23 namespace Events
  24 {
  25         class ModuleEventListener;
  26         class ModuleEventProvider;
  27 }
  28
  29 /** Provider of one or more cross-module events.
  30  * Modules who wish to provide events for other modules create instances of this class and use
  31  * one of the macros below to fire the event, passing the instance of the event provider class
  32  * to the macro.
  33  * Event providers are identified using a unique identifier string.
  34  */
  35 class Events::ModuleEventProvider : public ServiceProvider, private dynamic_reference_base::CaptureHook
  36 {
  37  public:
  38         struct Comp
  39         {
  40                 bool operator()(ModuleEventListener* one, ModuleEventListener* two) const;
  41         };
  42
  43         typedef insp::flat_multiset<ModuleEventListener*, Comp, std::less<ModuleEventListener*> > SubscriberList;
  44
  45         /** Constructor
  46          * @param mod Module providing the event(s)
  47          * @param eventid Identifier of the event or event group provided, must be unique
  48          */
  49         ModuleEventProvider(Module* mod, const std::string& eventid)
  50                 : ServiceProvider(mod, eventid, SERVICE_DATA)
  51                 , prov(mod, eventid)
  52         {
  53                 prov.SetCaptureHook(this);
  54         }
  55
  56         /** Get list of objects subscribed to this event
  57          * @return List of subscribed objects
  58          */
  59         const SubscriberList& GetSubscribers() const { return prov->subscribers; }
  60
  61         /** Subscribes a listener to this event.
  62          * @param subscriber The listener to subscribe.
  63          */
  64         void Subscribe(ModuleEventListener* subscriber)
  65         {
  66                 subscribers.insert(subscriber);
  67                 OnSubscribe(subscriber);
  68         }
  69
  70         /** Unsubscribes a listener from this event.
  71          * @param subscriber The listener to unsubscribe.
  72          */
  73         void Unsubscribe(ModuleEventListener* subscriber)
  74         {
  75                 subscribers.erase(subscriber);
  76                 OnUnsubscribe(subscriber);
  77         }
  78
  79  private:
  80         void OnCapture() CXX11_OVERRIDE
  81         {
  82                 // If someone else holds the list from now on, clear mine. See below for more info.
  83                 if (*prov != this)
  84                         subscribers.clear();
  85         }
  86
  87         /** Called when a listener subscribes to this event.
  88          * @param subscriber The listener which subscribed.
  89          */
  90         virtual void OnSubscribe(ModuleEventListener* subscriber) { }
  91
  92         /** Called when a listener unsubscribes from this event.
  93          * @param subscriber The listener which unsubscribed.
  94          */
  95         virtual void OnUnsubscribe(ModuleEventListener* subscriber) { }
  96
  97         /** Reference to the active provider for this event. In case multiple event providers
  98          * exist for the same event, only one of them contains the list of subscribers.
  99          * To handle the case when we are not the ones with the list, we get it from the provider
 100          * where the dynref points to.
 101          */
 102         dynamic_reference_nocheck<ModuleEventProvider> prov;
 103
 104         /** List of objects subscribed to the event(s) provided by us, or empty if multiple providers
 105          * exist with the same name and we are not the ones holding the list.
 106          */
 107         SubscriberList subscribers;
 108 };
 109
 110 /** Base class for abstract classes describing cross-module events.
 111  * Subscribers should NOT inherit directly from this class.
 112  */
 113 class Events::ModuleEventListener : private dynamic_reference_base::CaptureHook
 114 {
 115         /** Reference to the provider, can be NULL if none of the provider modules are loaded
 116          */
 117         dynamic_reference_nocheck<ModuleEventProvider> prov;
 118
 119         const unsigned int eventpriority;
 120
 121         /** Called by the dynref when the event provider becomes available
 122          */
 123         void OnCapture() CXX11_OVERRIDE
 124         {
 125                 prov->Subscribe(this);
 126         }
 127
 128  public:
 129         static const unsigned int DefaultPriority = 100;
 130
 131         /** Constructor
 132          * @param mod Module subscribing
 133          * @param eventid Identifier of the event to subscribe to
 134          * @param eventprio The priority to give this event listener
 135          */
 136         ModuleEventListener(Module* mod, const std::string& eventid, unsigned int eventprio = DefaultPriority)
 137                 : prov(mod, eventid)
 138                 , eventpriority(eventprio)
 139         {
 140                 prov.SetCaptureHook(this);
 141                 // If the dynamic_reference resolved at construction our capture handler wasn't called
 142                 if (prov)
 143                         ModuleEventListener::OnCapture();
 144         }
 145
 146         ~ModuleEventListener()
 147         {
 148                 if (prov)
 149                         prov->Unsubscribe(this);
 150         }
 151
 152         /** Retrieves the module which created this listener. */
 153         const Module* GetModule() const { return prov.creator; }
 154
 155         friend struct ModuleEventProvider::Comp;
 156 };
 157
 158 inline bool Events::ModuleEventProvider::Comp::operator()(Events::ModuleEventListener* one, Events::ModuleEventListener* two) const
 159 {
 160         return (one->eventpriority < two->eventpriority);
 161 }
 162
 163 /**
 164  * Run the given hook provided by a module
 165  *
 166  * FOREACH_MOD_CUSTOM(accountevprov, AccountEventListener, OnAccountChange, MOD_RESULT, (user, newaccount))
 167  */
 168 #define FOREACH_MOD_CUSTOM(prov, listenerclass, func, params) do { \
 169         const ::Events::ModuleEventProvider::SubscriberList& _handlers = (prov).GetSubscribers(); \
 170         for (::Events::ModuleEventProvider::SubscriberList::const_iterator _i = _handlers.begin(); _i != _handlers.end(); ++_i) \
 171         { \
 172                 listenerclass* _t = static_cast<listenerclass*>(*_i); \
 173                 const Module* _m = _t->GetModule(); \
 174                 if (_m && !_m->dying) \
 175                         _t->func params ; \
 176         } \
 177 } while (0);
 178
 179 /**
 180  * Run the given hook provided by a module until some module returns MOD_RES_ALLOW or MOD_RES_DENY.
 181  * If no module does that, result is set to MOD_RES_PASSTHRU.
 182  *
 183  * Example: ModResult MOD_RESULT;
 184  * FIRST_MOD_RESULT_CUSTOM(httpevprov, HTTPRequestEventListener, OnHTTPRequest, MOD_RESULT, (request));
 185  */
 186 #define FIRST_MOD_RESULT_CUSTOM(prov, listenerclass, func, result, params) do { \
 187         result = MOD_RES_PASSTHRU; \
 188         const ::Events::ModuleEventProvider::SubscriberList& _handlers = (prov).GetSubscribers(); \
 189         for (::Events::ModuleEventProvider::SubscriberList::const_iterator _i = _handlers.begin(); _i != _handlers.end(); ++_i) \
 190         { \
 191                 listenerclass* _t = static_cast<listenerclass*>(*_i); \
 192                 const Module* _m = _t->GetModule(); \
 193                 if (!_m || _m->dying) \
 194                         continue; \
 195                 result = _t->func params ; \
 196                 if (result != MOD_RES_PASSTHRU) \
 197                         break; \
 198         } \
 199 } while (0);