src/EventLoop.h

   1 /*
   2  * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_EVENTLOOP_H
  10 #define SQUID_EVENTLOOP_H
  11
  12 #include "time/forward.h"
  13
  14 #include <vector>
  15
  16 #define EVENT_LOOP_TIMEOUT  1000 /* 1s timeout */
  17
  18 class AsyncEngine;
  19
  20 /** An event loop. An event loop is the core inner loop of squid.
  21  * The event loop can be run until exit, or once. After it finishes control
  22  * returns to the caller. If desired it can be run again.
  23  \par
  24  * The event loop cannot be run once it is running until it has finished.
  25  */
  26 class EventLoop
  27 {
  28
  29 public:
  30     EventLoop();
  31
  32     /** register an async engine which will be given the opportunity to perform
  33      * in-main-thread tasks each event loop.
  34      */
  35     void registerEngine(AsyncEngine *engine);
  36
  37     /** start the event loop running. The loop will run until it is stopped by
  38      * calling stop(), or when the loop is completely idle - nothing
  39      * dispatched in a loop, and all engines idle.
  40      */
  41     void run();
  42
  43     /** run the loop once. This may not complete all events! It should therefor
  44      * be used with care.
  45      * TODO: signal in runOnce whether or not the loop is over - IDLE vs OK vs
  46      * TIMEOUT?
  47      */
  48     bool runOnce();
  49
  50     /** set the primary async engine. The primary async engine receives the
  51      * lowest requested timeout gathered from the other engines each loop.
  52      * (There is a default of 10ms if all engines are idle or request higher
  53      * delays).
  54      * If no primary has been nominated, the last async engine added is
  55      * implicitly the default.
  56      */
  57     void setPrimaryEngine(AsyncEngine * engine);
  58
  59     /** set the time service. There can be only one time service set at any
  60      * time. The time service is invoked on each loop
  61      */
  62     void setTimeService(Time::Engine *);
  63
  64     /** stop the event loop - it will finish the current loop and then return to the
  65      * caller of run().
  66      */
  67     void stop();
  68
  69     int errcount;
  70
  71     /// the [main program] loop running now; may be nil
  72     /// for simplicity, we assume there are no concurrent loops
  73     static EventLoop *Running;
  74
  75 private:
  76     /** setup state variables prior to running */
  77     void prepareToRun();
  78
  79     /** check an individual engine */
  80     void checkEngine(AsyncEngine * engine, bool const primary);
  81
  82     /** dispatch calls and events scheduled during checkEngine() */
  83     bool dispatchCalls();
  84
  85     bool last_loop;
  86     typedef std::vector<AsyncEngine *> engine_vector;
  87     engine_vector engines;
  88     Time::Engine *timeService;
  89     AsyncEngine * primaryEngine;
  90     int loop_delay; /**< the delay to be given to the primary engine */
  91     bool error; /**< has an error occurred in this loop */
  92     bool runOnceResult; /**< the result from runOnce */
  93 };
  94
  95 #endif /* SQUID_EVENTLOOP_H */
  96