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
64class 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__
127