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  * Authors: Gabe Black
  28  */
  29
  30 #ifndef __BASE_FIBER_HH__
  31 #define __BASE_FIBER_HH__
  32
  33 // ucontext functions (like getcontext, setcontext etc) have been marked
  34 // as deprecated and are hence hidden in latest macOS releases.
  35 // By defining _XOPEN_SOURCE we make them available at compilation time.
  36 #if defined(__APPLE__) && defined(__MACH__)
  37 #define _XOPEN_SOURCE 600
  38 #include <ucontext.h>
  39 #undef _XOPEN_SOURCE
  40 #else
  41 #include <ucontext.h>
  42 #endif
  43
  44 #include <cstddef>
  45 #include <cstdint>
  46
  47 #include "config/have_valgrind.hh"
  48
  49 /**
  50  * This class represents a fiber, which is a light weight sort of thread which
  51  * is cooperatively scheduled and runs sequentially with other fibers, swapping
  52  * in and out of a single actual thread of execution.
  53  *
  54  * To define your own threads, create a subclass of Fiber and override its
  55  * main() function to do what you want your fiber to do. You can start it by
  56  * calling its run() method which will stop your execution and start the other
  57  * fiber in your place.
  58  *
  59  * If your main() function ends, that fiber will automatically switch to either
  60  * the primary fiber, or to a particular fiber you specified at construction
  61  * time, and your fiber is considered finished.
  62  */
  63
  64 class Fiber
  65 {
  66   public:
  67     const static size_t DefaultStackSize = 0x50000;
  68
  69     /// stack_size is the size of the stack available to this fiber.
  70     /// link points to another fiber which will start executing when this
  71     /// fiber's main function returns.
  72     Fiber(size_t stack_size=DefaultStackSize);
  73     Fiber(Fiber *link, size_t stack_size=DefaultStackSize);
  74
  75     virtual ~Fiber();
  76
  77     /// Start executing the fiber represented by this object. This function
  78     /// will "return" when the current fiber is switched back to later on.
  79     void run();
  80
  81     /// Returns whether the "main" function of this fiber has finished.
  82     ///
  83     bool finished() const { return _finished; };
  84
  85     /// Returns whether the "main" function of this fiber has started.
  86     ///
  87     bool started() const { return _started; };
  88
  89     /// Get a pointer to the current running Fiber.
  90     ///
  91     static Fiber *currentFiber();
  92     /// Get a pointer to the primary Fiber.
  93     /// This Fiber represents the thread of execution started by the OS, and
  94     /// which has a Fiber attached to it after the fact.
  95     static Fiber *primaryFiber();
  96
  97   protected:
  98     /// This method is called when this fiber is first run. Override it to
  99     /// give your fiber something to do. When main returns, the fiber will
 100     /// mark itself as finished and switch to its link fiber.
 101     virtual void main() = 0;
 102
 103     void setStarted() { _started = true; }
 104
 105   private:
 106     static void entryTrampoline();
 107     void start();
 108
 109     ucontext_t ctx;
 110     Fiber *link;
 111
 112     // The stack for this context, or a nullptr if allocated elsewhere.
 113     void *stack;
 114     size_t stackSize;
 115     void *guardPage;
 116     size_t guardPageSize;
 117 #if HAVE_VALGRIND
 118     unsigned valgrindStackId;
 119 #endif
 120
 121     bool _started;
 122     bool _finished;
 123     void createContext();
 124 };
 125
 126 #endif // __BASE_FIBER_HH__