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