include/event.h

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