src/base/fiber.hh

   1 /*
   2  * Copyright 2018 Google, Inc.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are
   6  * met: redistributions of source code must retain the above copyright
   7  * notice, this list of conditions and the following disclaimer;
   8  * redistributions in binary form must reproduce the above copyright
   9  * notice, this list of conditions and the following disclaimer in the
  10  * documentation and/or other materials provided with the distribution;
  11  * neither the name of the copyright holders nor the names of its
  12  * contributors may be used to endorse or promote products derived from
  13  * this software without specific prior written permission.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  17  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  18  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  19  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  20  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  21  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  25  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef __BASE_FIBER_HH__
  29 #define __BASE_FIBER_HH__
  30
  31 // ucontext functions (like getcontext, setcontext etc) have been marked
  32 // as deprecated and are hence hidden in latest macOS releases.
  33 // By defining _XOPEN_SOURCE we make them available at compilation time.
  34 #if defined(__APPLE__) && defined(__MACH__)
  35 #define _XOPEN_SOURCE 600
  36 #include <ucontext.h>
  37 #undef _XOPEN_SOURCE
  38 #else
  39 #include <ucontext.h>
  40 #endif
  41
  42 // Avoid fortify source for longjmp to work between ucontext stacks.
  43 #pragma push_macro("__USE_FORTIFY_LEVEL")
  44 #undef __USE_FORTIFY_LEVEL
  45 #include <setjmp.h>
  46 #pragma pop_macro("__USE_FORTIFY_LEVEL")
  47
  48 #include <cstddef>
  49 #include <cstdint>
  50
  51 #include "config/have_valgrind.hh"
  52
  53 /**
  54  * This class represents a fiber, which is a light weight sort of thread which
  55  * is cooperatively scheduled and runs sequentially with other fibers, swapping
  56  * in and out of a single actual thread of execution.
  57  *
  58  * To define your own threads, create a subclass of Fiber and override its
  59  * main() function to do what you want your fiber to do. You can start it by
  60  * calling its run() method which will stop your execution and start the other
  61  * fiber in your place.
  62  *
  63  * If your main() function ends, that fiber will automatically switch to either
  64  * the primary fiber, or to a particular fiber you specified at construction
  65  * time, and your fiber is considered finished.
  66  */
  67
  68 class Fiber
  69 {
  70   public:
  71     /**
  72      * @ingroup api_fiber
  73      */
  74     const static size_t DefaultStackSize = 0x50000;
  75
  76     /**
  77      * @param Link points to another fiber which will start executing when this
  78      *     fiber's main function returns.
  79      * @param stack_size is the size of the stack available to this fiber.
  80      *
  81      * @ingroup api_fiber
  82      * @{
  83      */
  84     Fiber(size_t stack_size=DefaultStackSize);
  85     Fiber(Fiber *link, size_t stack_size=DefaultStackSize);
  86     /** @} */ // end of api_fiber
  87
  88     /**
  89      * @ingroup api_fiber
  90      */
  91     virtual ~Fiber();
  92
  93     /**
  94      * Start executing the fiber represented by this object. This function
  95      * will "return" when the current fiber is switched back to later on.
  96      *
  97      * @ingroup api_fiber
  98      */
  99     void run();
 100
 101     /**
 102      * Returns whether the "main" function of this fiber has finished.
 103      *
 104      * @ingroup api_fiber
 105      */
 106     bool finished() const { return _finished; };
 107
 108     /**
 109      * Returns whether the "main" function of this fiber has started.
 110      *
 111      * @ingroup api_fiber
 112      */
 113     bool started() const { return _started; };
 114
 115     /**
 116      * Get a pointer to the current running Fiber.
 117      *
 118      * @ingroup api_fiber
 119      */
 120     static Fiber *currentFiber();
 121
 122     /**
 123      * Get a pointer to the primary Fiber.
 124      * This Fiber represents the thread of execution started by the OS, and
 125      * which has a Fiber attached to it after the fact.
 126      *
 127      * @ingroup api_fiber
 128      */
 129     static Fiber *primaryFiber();
 130
 131   protected:
 132     /**
 133      * This method is called when this fiber is first run. Override it to
 134      * give your fiber something to do. When main returns, the fiber will
 135      * mark itself as finished and switch to its link fiber.
 136      */
 137     virtual void main() = 0;
 138
 139     void setStarted() { _started = true; }
 140
 141   private:
 142     static void entryTrampoline();
 143     void start();
 144
 145     ucontext_t ctx;
 146     // ucontext is slow in swapcontext. Here we use _setjmp/_longjmp to avoid
 147     // the additional signals for speed up.
 148     jmp_buf jmp;
 149
 150     Fiber *link;
 151
 152     // The stack for this context, or a nullptr if allocated elsewhere.
 153     void *stack;
 154     size_t stackSize;
 155     void *guardPage;
 156     size_t guardPageSize;
 157 #if HAVE_VALGRIND
 158     unsigned valgrindStackId;
 159 #endif
 160
 161     bool _started;
 162     bool _finished;
 163     void createContext();
 164 };
 165
 166 #endif // __BASE_FIBER_HH__